User Guides Content Management and Delivery

Overall

Electronic or printed user guides are currently not exisiting for OpenPetra.

The goal of this project is to set up the technical platforms for editing, creating and publishing of the electronic, printable user guides in the PDF ouptut format. Writing the content is not part of this project (with the exception of the creation of limited content to prove that the technical platforms work as desired).

The technical platform should be Confluence or Calenco, as mentioned in the section 'Tools for Evaluation', for the major parts of what we want to achieve with this project.

Requirements

The requirements listed here are in addition to what is listed in the section 'Requirements'!

Key Requirements

Book-like Formatting

Imagine producing a book out of the input document(s) (Confluence Wiki page(s) or DocBook file(s) in case of Calenco), or producing something like the existing Petra 2.x User Guides. In general, we would like the output to look similar to the existing Petra 2.x User Guides.

To achieve a 'book-like' output, rather than the 'bland' look of an average electronic document, the PDF output needs to feature the following formatting capabilities:

• Cover (Title) Page
  • A single graphic should be possible
    • Horizontally centred, vertical position: vertically centered or user specified
  • Several lines of text should be possible
    • Horizontally centred, vertical position: user specified for each line of text
    • Individual formatting for each line of text (e.g. typeface, size, bold, italic, underline) must be possible
• Back Cover Page
  • The opposite to the Cover (Title) Page of a book or user guide: the last page in the document.
  • Could simply be empty or could have a copyright notice at the bottom (e.g. '(c) 2012 by OpenPetra.org and its contributors').
• Table of Contents (TOC)
  • Built automatically from 1st to 3rd (or possibly 4th) level Headings
  • Page Numbers should be hyperlinks in the PDF document so the user can click on any page number and the Adobe Reader jumps there.
• Index
  • See examples in the Petra 2.x User Guides.
  • Page Numbers should be hyperlinks in the PDF document so the user can click on any page number and the Adobe Reader jumps there.
  • Auto-generated index entries?
    • Built automatically from most words that are not 'stop words' ['and', 'or', ...] and not numbers ('2012')?
  • Manually specified index entries?
    • Some form of mark-up in the document would be needed (see how this is done in MS Word, for instance).
  • Mix of auto-generated and manually specified index entries?
• Page Headers and Page Footers
  • See examples in the Petra 2.x User Guides.
• Page Numbering
  • No numbering on Title Page, Back Cover Page (see Optional Features)
  • Numbering in roman letters (xx, xxi, etc.) for pages in the Table of Contents, then starting with latin letter 1 for the main content of the user guide.
• Margins
  • Top and bottom margins (always the same on every page)
  • Even/odd margins (=margins mirrored for pages left and right from the middle gutter)
• Chapter End: Page Break
  • Insert a page break after a Level-1-Heading text (=chapter) ends (see also Optional Features).

Optional Features

Chapter End: 'Blank Page' With Note

Rather than inserting a page break as descibed unter 'Chapter End: Page Break' above, insert a new page that is empty except for the words 'This page left empty' in light-grey text colour. See examples in the Petra 2.x User Guides.

Expected Outcome

General

Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones here, should be made with both Confluence and Calenco.

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

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

All requirements must be met, if optional features are present then this is a bonus.

Assessments

The PDF output will be compared with the WebHelp output from the same source(s) (wiki pages, DocBook document(s)). The expected differences will be looked at and any unexpected differences or content that should/should not be present in the PDF will be checked for.

ChristianK and MatthiasS will assess the PDF created for its suitability for on-screen reading and for printing as follows:

• Assessing document on-screen
  • Page Numbers in Table of Contents (TOC) and Index must be hyperlinks that direct Acrobat Reader to jump to the corresponding page.
  • Any colours used (except for colours in graphics which are part of the content) must look 'OK' and must be well distinguishable when viewed on screen (checks with different screens/screen colour settings might be done).
• Assessing document when printed
  • Overall look-and-feel when printed will be assessed.
  • Any colours used (except for colours in graphics which are part of the content) must look 'OK' and must be well distinguishable when printed - in colour and in black-and-white! (Checks with different printer driver settings on our colour laser printer will be done).
  • Any icons used must look 'OK' and must be well distinguishable when printed - in colour and in black-and-white! (Checks with different printer driver settings on our colour laser printer will be done).
  • Similarity in appearance and usability to current Petra 2.x User Guides will be judged (but don't let this be a major 'driver' for you, i.e. don't spend too much time on re-creating the 'exact' look!).