Common Goals for the Two Documentation-related Projects

Overall

OpenPetra currently does not have application help (usually launched with the 'F1' key). Electronic or printed user guides do not exist yet either.

The goal of the two documentation-related projects is to set up the technical platforms for editing, creating and publishing of the application help and the (printable) electronic user guides (the latter one in PDF format). Writing the content is not part of this project (with the exception of the creation of very limited content to prove that the technical platforms work as desired).

The technical platforms should use one of the two tools mentioned in the section 'Tools for Evaluation' for the major parts of what we want to achieve with the two projects.

Requirements

Single Source Publishing

Both the content of the application help and the content of the electronic user guides should be authored with the same 'tool'.
- There are many advantages of using 'Single Source Publishing' rather than maintaining content independently - from fixing (spelling) mistakes to renaming e.g. menu items in the documentation in a single place.
The work-flow for the creation of both output formats should be similar.

Content Re-use

The content of the application help should be re-usable in the user guides and vice versa. Although application help and user guides are different media, the content (and not the form and layout) is the key in both cases.

Supported content should be text and graphics in both cases.

Easy Contribution

The 'tool' for writing the content for the application help and the electronic user guides - and specifically its setup - needs to be geared towards welcoming various technical writers (who might well be volunteers). Thus, the process to creation of a new user who would work on content for the application help or/and the electronic user guides needs to be easy and well-documented.

WYSIWYG-near Editing

The editor for writing content for the application help and the electronic user guides needs to support 'WYSIWYG-near editing', that is, rather than writing and seeing mark-up (as e.g. in HTML) the technical writer needs to be able to use buttons with icons for such formatting purposes (e.g. assigning typeface, size, bold, italic, underline) and see the effect on the formatting of the text visually in the editor at once.

This is 'WYSIWYG-near' rather than 'WYSIWYG' formatting because the technical writer doesn't see the actual formatting of the final document (e.g. application help page or user guide page), but the formatting of the content only.

Good Control Over Output

There needs to be good control of the layout in which the application help appears and over the layout of the electronic user guides in PDF format. This includes: headings (for chapters and sub-chapters), text and text formatting (e.g. typeface, size, bold, italic, underline), graphics and the positioning of graphics in relation to text. Also, it should be possible to always format certain elements of the content in exactly the same way (e.g. 'Warning', 'Information' or 'step-by-step' instruction sections).

In the case of application help this includes also the appearance of: links, logos.
In the case of electronic user guides in PDF format this includes also the appearance of: Cover (Title) Page, Back Cover Page, Table of Contents (TOC), Index, Page Headers and Footers, Page Numbering, Margins, Chapter End: Page Break.
Highlighting of 'Warning', 'Information' or 'Step-by-Step' instruction sections
- Sections of the document content that contain a warning (which, if not followed, could have bad consequences), information (additional insights or tips pertainting to the current text section) should be set out from the normal content layout as follows:
  - Draw a rectangle around the warning or information content.
    - Background could have a light colour shade, eg. 10% Grey.
  - Set the rectangle off from the other content with a top and bottom margin.
  - Perhaps include an Icon (e.g. similar to the Windows 'Error' and 'Information' icons). Size: 32x32 or 64x64 pixels.
- Sections of the document content that contain a 'Step-by-Step' instruction should be easily identifyable by their layout.
  - Play around with varying layout options you can think of, perhaps including an appropriate Icon (Size: 32x32 or 64x64 pixels).
  - Please note that such sections can be quite long and, in electronic user guides, often span a page break, when considering the layout options.

Translation

The content of the application help and user guides should be translatable into various languages. This includes the need for storing graphics in different languages as well (they might contain text!) and referencing them in the appropriate language of the content.

Documentation Versioning

For different program versions of OpenPetra we need to be able to produce and access different 'versions' of the application help and we need to be able to produce different 'versions' of the electronic user guides, namely the application help/electronic user guide contents that are tailored for each program version (e.g. OpenPetra V1.0, OpenPetra V1.5).

Optional Features

Content Versioning

It would be desirable to be able to have an internal versioning of the content, with a new 'version' being created each time one edits and saves a block of the content.

Change Tracking

On top of that, it would be very good to have the ability to compare different versions of the content in order to easily find out what has been changed, and by which user and when. For the electronic user guides, an easy way of doing a side-by-side comparison of what has changed in the layout of the user guides would be nice, in addition to the information about what has been changed (and by whom) in the content.

Approval Workflow

It would be nice to have the ability to have the translations of our application help and electronic user guides to be approved in a way that Person 'A' writes a draft of a translation, asks Person 'B' to review and approve it, Person 'B' may reject it for some reasons and return it to Person 'A' who wrote the draft with some comments on what needs to change, Person 'A' in turn improves the document and again asks Person 'B' for further review and approval, who in the end approves the document. We would like only 'approved' documents to be ending up in the application help and electronic user guides and would like to be able to see a trail of the approval process of each document and its versions.

Tools for Evaluation

Main Tools

We want to use one of the following tools for meeting the requirements and possibly the optional features:

Confluence
Calenco

Both products are commercial, but there are free versions available for open source projects, and it is those we are evaluating. We have installations for both products set up.

Please note that the Calenco FREE version we are using does not have the full functionality of the non-free product, esp. the functionality of editing of text is missing - hence we need to use a separate DocBook XML Editor (see below).

Plug-Ins for Confluence

Several of those plug-ins are commercial, but since we have a free installation of Confluence for an open source project these are free as well. These plug-ins have been installed in our Confluence installation.

Editing DocBook XML Files

For editing the DocBook XML files which are the input for at least the application help (='WebHelp') output, and at least in the case of Calenco also the PDF output, the use of the following visual DocBook XML Editors should be evaluated:

Both products are commercial, but there are free versions available for open source projects, and it is those we are evaluating. We have installations for both products set up. We will end up using the editor that has the best feature set for our purposes and is easiest to use.

Note: For the creation of PDF user guides from Confluence the ScrollWiki PDF Exporter Plug-in might suffice. If it does not, then the ScrollWiki DocBook Exporter Plug-in could be used first to create a DocBook file, which could then be used with Calenco PDF Output to see if better formatted output could be achieved.

WebDAV Access

For the continued editing of DocBook files with Calenco we will use the WebDAV protocol, which the Calenco server exposes. This way we don't need to repeatedly upload files again and again, but can simply access and edit files (once they are initially uploaded) as if they were local files and not files on the Calenco server. While Windows supports the mounting of WebDAV folders, there is a bug in Windows that also affects our Windows server and which in turn is therefore not able to mount such a WebDAV folder successfully. To overcome that, ChristianK trialled several free WebDAV clients for Windows, of which Red Drive seems to work fine.

Red Drive is installed on the server and creates a new drive in the 'My Computer' section of Windows Explorer called 'Red Drive', which needs to be set up once to point to the location of the WebDAV address of Calenco for every user on the Calenco server. This is already done for ChristianK, but for the student users this needs to be done once for each student. To do this, right-click the 'Red Drive' in the Windows Explorer and choose 'New Connection'. In the following dialog select 'WebDAV' as the protocol, entering 'http://localhost:9000/workspaces/OpenPetraDOCS/content/' as the URL, 'Student 1' or 'Student 2' for the 'Name' and enter your Calenco credentials in the 'Username' and 'Password' fields. This 'Red Drive' can now be used in XMLmind and Xerna Free to open and save files directly from/to the Calenco server - either by right-clicking the file name in the 'Red Drive' and choosing 'Open With...' and selecting 'xxe' for XMLmind and 'Syntext Serna Free 4.4.0' or by opening a file directly from within XMLmind or Serna Free, choosing 'My Computer'/'Red Drive' as the starting path, followed by the Red Drive username.

Expected Outcome

Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones on the two documentation-related projects pages, should be made with both 'Main Tools' (Confluence, Calenco).

Once this is done with both products, a write-up should be done of the 'pros' and 'cons' of each products.

Based on the write-up we will make a judgement. We are then planning to use our favoured product for the purposes of authoring application help and electronic user guides for OpenPetra.