Voyager Support

Voyager is a very complex projects and it just can be successful when everyone contributes as good as possible. To make it easier for you to join the project we defined some jobs where you might help.

Documentation
Good documentation is an important part of Voyager. For various reasons we decided to do the documentation in DocBook. This is an XML based format used for many publications, O'reilly books are done with that too. Many other open source projects use this format as a base, it allows us to create any kind of output out of it like HTML or PDF but also more in the future.

The drawback is that it takes some more time to get into DocBook, in the beginning it is easier to use a WYSIWYG application like OpenOffice.org to create the document. Currently two Voyager developers write their documentation in OpenOffice.org.

So one help would be to keep [The Design of Voyager] up to date with the OpenOffice.org documents of the two developers. Beside this one might also work on an easy to use way on eCS to work with DocBook.

DocBook Editors
At the time writing there are the following options available to edit DocBook in an easier way:


 * Eclipse with the Vex and XMLBuddy plugin. Vex is open source and XMLBuddy is free in the entry version which is enough for our needs. Unfortunately we do not have an Eclipse port for eCS yet so this requires to work on one of the supported Eclipse platforms right now.
 * XMLmind, a standalone Java based XML Editor which seems to support DocBook as well. According to the requirements this should work on eCS but we did not test that yet. It would be nice to set up a package that can be easily installed on eCS.

At Warpstock Europe 2005 there was also a presentation about DocBook on eCS by Jarda Kačer and Jirka Kosek. It would be a good idea to work together with those guys to get that to work on eCS as well.

DocBook Syntax
The best way to learn DocBook is to have a look at the current book, most of the needed tags are probably already used once. Beside this one should have a look at DocBook: The Definitive Guide, which is available online or as HTML download.

Some remarks:
 * Use xref whenever possible to create a reference to another part of the document. This makes reading the book much more interactive.
 * For images one should use PNG versions for the web release and PDF for the PDF edition of the book. See the mediaobject example in Chapter 3. Please make sure that the PNG versions use a size that makes sense for web publishing. We did not do many tests on PDF yet, we have to see how this works regarding scaling.
 * We use Subversion to keep a history of the document, this also means that the structure of the document should not change unless there is new content. Because of its XML nature, every editor will use its own indenting for the file. The only valid format to commit to Subversion is the indenting of Vex. So in case your editor changes the layout please make sure that Vex did format it before it gets committed, otherwise we get very big changesets!

ToDo
This is a list of documents that need to get maintained.

Netlabs Object Model

 * Object Design
 * Author: Chris Wohlgemuth, cinc at netlabs.org, Cinc on irc://irc.netlabs.org/netlabs

Desktop

 * Desktop Design
 * Author: Chris Wohlgemuth, cinc at netlabs.org, Cinc on irc://irc.netlabs.org/netlabs

Triton

 * MMIO General - OpenOffice.org
 * Author: Peter Kocsis, FIXME, Doodle on irc://irc.netlabs.org/netlabs

Object-Oriented Interface Design (CUA)
This is the book written by IBM back in the early nineties, the original title was
 * Object-Oriented Interface Design - IBM Common User Access Guidelines ISBN 1-56529-170-0

We never found a PDF version of this book, just a very poor online HTML version. With the help of some scripts we assembled a standalone version of this book. Unfortunately the HTML syntax is very poor and the book lacks the images. Good for you because you can help us on that ;-)


 * Get the recent version of this book in our Subversion
 * Install NVU and open the xhtml file.
 * Start to clean it up. The syntax should look like in the beginning, very simple but clean XHTML code, as few   as possible, ,   for topic formating and   for paragraphs.
 * Kill all table of contents and such things in the XHTML version. We will transform the XHTML to DocBook in a second step and DocBook will take care of that.
 * And if you are brave try to reproduce the images, at least those that make sense. This book is still available second hand, use that as a reference. For sure it would greatly help if someone finds a PDF version of the original document (in case that exists). It might get pretty tricky to reproduce some of the images because IBM created some sample applications for it, use what makes sense to you.