Ideas for Realising Some Specific Goals

For some goals we have proposed ideas or solutions on how they could be achieved, either in Confluence or in Calenco, or in both. For other goals, solutions still need to be found...

Content Re-use

A key to content re-use between application help and electronic user guides is that it must be possible to omit some content in one of the output formats. In other words: it must be possible to make a distinction in the content depending on whether we want to create the application help files or the PDF User Guides from the wiki pages/DocBook files (some part of the content of a wiki page/DocBook files should only be available in the Help files, where other content of a wiki page should only be available in a PDF User Guide).

Realising this with Confluence

Utilising the CustomWare Visibility Plugin Hide-if and Show-if macros. All Scroll Wiki Exporters export only the content the current user has permission for, so if one would log in to Confluence as a user for publishing application help then the content that is only visible for the user that is publishing the user guides would be omitted, and vice versa.

Some content is automatically excluded/included depending on what format is being exported. Otherwise use Scroll Wiki macros to exclude content from being viewed:

• Scroll docbook ignore
• Scroll pdf ignore
• Scroll ignore (all exports do not include the content)

Idea for realising this with Calenco: Utilising the the filtering system of Calenco. It can be adapted for any filtering one can imagine. Filtering rules can be crossed too.

Question to Calenco support staff: "Can (a set of) filtering rules be attached to an Output Processor, e.g. could one (set of) filtering rule(s) be attached to the PDF Output Processor and another (set of) filtering rule(s) be attached to the WebHelp Output Processor. The effect of being able to do so would be that by choosing a particular Output Processor the filtering rules for that Output Processor would be in effect automatically and therefore one cannot forget to set them up before starting to output documents using the Output Processors." Answer from Calenco support staff: "Yes. One can define as many publications as needed on a defined Document. A publication is defined through a publication form that defines the output format, stylesheet, filtering options, etc. Therefore filtering options can be set as defaults in a stylesheet, or specifically for a publication."

Content Tailoring for Different Organisations

See previous paragraph 'Content Re-use'.

Good Control Over Output

• Highlighting of 'Warning', 'Information' or 'Step-by-Step' instruction sections
  • The appearance of such sections should be defined once in a DocBook stylesheet (possibly separately for the DocBook stylesheets for application help and electronic user guides) and then applied to the desired content by choosing the appropriate definitions from the stylesheet in the DocBook Editor or by using the Confluence Wiki Markup that will result in the Scroll Wiki output processor using the appropriate definition from the stylesheet(s).

Realising Good Control Over Output with Confluence

Translation

Realising this with Confluence

If the content is available in different languages one can export different subsets from a wiki space with the Scroll Wiki Exporters. Have different root pages for each language, and just export from them and include their children. Also, maybe use labels to identify what language is being used, and export using children with label?

Realising this with Calenco: Calenco supports content in various languages, as well as the 'International' (invariant) language. See the Calenco User Guide on how to achieve this.

Documentation Versioning

Realising this with Confluence

Sort of resolved by Atlassian as described here: [1]

Idea for realising this with Calenco: There should be various ways to achieve this, one of which would be to store a copy of a version in a different directory once content for a new version is to be written and from then on work on the two copies independently (e.g. have a /en/v1.0/ directory, and - once content for e.g. v1.5 is to be written - copy all sub-folders of /en/v1.0/ to /en/v1.5/).

URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified

Realising this with Confluence

Using the 'page name' of Confluence. This works as long page names don't change! There is also a 'pageId', which is the unique id in the Confluence database which could also be used, but that approach doesn't work if one migrates or copies Confluence spaces, etc. (which will be done for Application Versioning [V1.0, V1.5, ...] reasons!).

Realising this with Calenco: This is achieved by specifying IDs to the parts being referenced in the XML, and by telling the stylesheet to use them to name the output files.

Optional Features

Change Tracking

Realising this with Confluence: Textual or even visual change tracking should be easily possible (after all, that's what a wiki can do very well!). It is very easy to compare what was changed between versions just like all wikis.

Idea for realising this with Calenco: The full version of Calenco provides a visual change tracking feature, but the FREE version we use doesn't.

We suspect that there should be separate tools available that allow at least textual, if not visual change tracking on DocBook XML files. Find and evaluate at least one such tool, which will need to be freeware or free for open source projects, and if you found more than one we will choose to go with the best tool you have found.

Approval Workflow

Realising this with Confluence: Utilising the Ad hoc Workflows Plugin, tasks can be assigned to particular users (although other users can "complete" them), but approval assignments work very well, and history of comments, approval, denial, etc. is kept track of in the "activity" option along the top of the article.

Idea for realising this with Calenco: Users could use some Calenco Classifications such as Official documents, Drafts to manage documents. In order to add comments, the WebHelp output which can include a Comment functionality could be used (see here) - also if the output should be a user guide in the end.