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 is useful for showing content for specific organizations. 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)
Realizing 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
Realizing with Calenco
This was a hard tasks mostly because to get the exact desired output a completely custom xslt stylesheet was needed.
- Any desired type of formatting can be achieved but, the trouble was figuring our how to do so in a stylesheet.
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?
Content Internationalizer seems nice, but is outdated
Realising this with Calenco
Calenco supports content in various languages.
- Essentially each language is broken down into a workspace. You upload desired documents into their corresponding language and then they are only visible within that workspace. The international workspace is available to all sections, this is where you store custom stylesheets that you would want to use with various documents.
Documentation Versioning
Realising this with Confluence
Sort of resolved by Atlassian as described here: [1]
Idea for realising this with Calenco
In Calenco it is possible to create directories in each workspace. Therefore one could have sub directories of a workspace for each version (ex. /en/v1 and /en/v1.1). One could copy old files from v1 directory to v1.1 directory and thus modify only v1.1 document by editing it in that directory.
URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified
Realising this with Confluence
- Suggested way of doing it: "Use 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!)."
- We haven't yet figured out how to achieve that using the Scroll Wiki DocBook Exporter plug-in, though. The plug-in assigns unique, automatically numbered ID Attributes to <section> elements in the DocBook output file and we haven't found an option to change that behaviour. The result is that the names of HTML files and the names of Anchors in those HTML files in the WebHelp output aren't static, but change once sections are inserted between sections as they take on the ID Attribute values from the DocBook file.
- Potential solution: Should there be no way of making this work with the Scroll Wiki DocBook Exporter plug-in then we could write for ourselfes a small commandline .NET executable that would re-write all the ID Attributes of the DocBook file to the title of the following <section> Element. Calling this executable as a first step before the current first step in the WebHelp toolchain would give us static names of HTML files and static names of Anchors in the HTML files.
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.