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: title page, table of content, index, page headers and footers, page numbering, margins.
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
We want to use one of the following tools for meeting the requirements and possibly the optional features:
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.
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 products.
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.