Common Goals for the Two Documentation-related Projects

From OpenPetra Wiki
Revision as of 15:29, 4 January 2012 by Christiankatict (talk | contribs) (Created page with '==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 t…')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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).

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.

Retrieved from ‘https://wiki.openpetra.org/index.php?title=Common_Goals_for_the_Two_Documentation-related_Projects&oldid=2762’