notice - Note
So the information below is outdated.
- 1 Goals
- 2 Pros and cons
- 3 Milestones
- 4 Budget
- 5 Tasks
- 6 Tools
This project was born out of discussions about the need to make TYPO3 v4 and FLOW3/TYPO3 Phoenix documentation converge. TYPO3 v4 documentation is still based on OpenOffice, whereas FLOW3/TYPO3 Phoenix documentation is based on DocBook. Furthermore the designs used are not the same, which is not good for users, nor for the TYPO3 brand.
Migrating the TYPO3 v4 documentation to DocBook had been a long-standing idea. The fact that this technology was already used by the FLOW3/TYPO3 Phoenix documentation and the need to converge with the latter has set this project into motion again.
The goals of this project are thus:
- to migrate all the official documentation of TYPO3 v4 to DocBook
- to define a common design for TYPO3 v4 and FLOW3/TYPO3 Phoenix manuals
- to adapt the FLOW3/TYPO3 Phoenix manuals to the common format and design
- to define a number of DocBook transformations providing professional documentation for TYPO3 and related projects
- tell the exact line number when a validation error of a manual occurs
Pros and cons
The decision to revive the migration to DocBook for TYPO3 v4 documentation was not preceded by a public (i.e. community-wide) debate. This was deemed appropriate as a) the idea was already in the air, b) DocBook brings some very real advantages to the documentation process.
- strict separation of structure/content and design. DocBook describes the structure of the document and stores its content. The design is applied only during the rendering process. This makes it far easier to ensure layout consistency than with OpenOffice.
- enforcement of structure: it's possible to define the exact structure to be used in the manuals and to enforce using a validation schema (in Relax NG).
- plentiful rendering possibilities. It is possible to convert DocBook to a wide variety of formats. Such transformations need be only coded once, which means it is possible to create very clean renderings, better than what is achievable from OpenOffice.
- text-based format. A long-standing problem of the use of OpenOffice was the binary format of OpenOffice files. Because of this it was not possible to keep track of changes via a Version Control System. This restricted the opening of some manuals (in particular core manuals) to more editors, thus creating a bottleneck in the maintenance process.
- DocBook, once learned is similar and as easy to use as HTML (slight Con: it takes a little time to learn)
- DocBook is obviously harder to use than OpenOffice, which is a simple word processor. This is somewhat mitigated by the fact that editors won't need to worry about style anymore. Also the enforcement of structure gives a better framework within which to work.
- the TER needs to be adapted, although it does use DocBook already (transformation process: OpenOffice => DocBook => HTML). But the TER processes related to documentation are badly in need of a refresh anyway.
- of course, the existing documents need to be migrated. This is probably going to be quite an important workload, as it is not clear yet whether the export from OpenOffice to DocBook can really be of any use if we want to have clean structures.
Below are a number of milestones that represent a first organization of the project into several large steps. This should probably be improved. Some steps can be performed - or at least started - in parallel.
For all milestones you find the issues here: Forge Project DocBook-migration . Just add this a bookmark in your browser.
Define the DocBook document structure that covers the needs of the TYPO3 v4 + v5 documentation. The result will a Relax NG schema against which all official manuals must validate. The structure will also be documented. A sample v4 manual will be converted during that phase.
Create all the rendering scripts for the various output formats. This phase includes defining the design for the manuals in various formats (for the HTML rendering this will of course be in line with the design of typo3.org).
Files: First version of API Doc, ter_doc_html/static/css/setup.txt
Dedicated page: DocBook_migration/DocBook_Design_Elements
Convert the main v4 manuals to DocBook. Modify existing FLOW3 and v5 manuals to match the chosen DocBook structure.
Make the necessary changes to TER and typo3.org so that the new manuals can be displayed and downloaded properly.
Provide an on-line tool for collaboratively editing DocBook manuals.
This project benefits from a budget allocation from the TYPO3 Association, thanks to a budget request made by François Suter.
The estimate for the budget were based on the above milestones:
- Milestone 1: 3 man-days
- Milestone 2: 5 man-days
- Milestone 3: 5 man-days
- Milestone 4: 3 man-days
- Milestone 5: 15 man-days
- Total: 31 man-days
This total is not expected to cover all the work to do (far from it), but to help compensate participants for their efforts and pay for some of the harder or more boring tasks ahead.
Most of the actual tasks for the many steps to take have not yet been defined. There are however a couple of early tasks that are up for grabs:
- Inquire into print-on-demand:
- what providers are there out there? They should be global players to ensure that TYPO3 manuals can be bought world-wide. Note: one well-known such provider is lulu.com.
- what are the (financial) conditions of these providers?
- are there any particular technical issues to consider when preparing a file for print-on-demand?
Brainstorming and notes
Here is a mind map I use for thinking about the project and taking notes. I write down everything, from conceptual stuff down to small details. It's not about project management, it's about trying to think about all aspects.
Some other things to keep in mind:
- an interesting way to handle user comments, on a per-paragraph basis, done in the Mercurial documentation: http://hgbook.red-bean.com/read/managing-releases-and-branchy-development.html
This is a list of tools that can be used to work with DocBook files.
- oXygen: commercial, quite expensive, but with a very good reputation (there's an non-commercial license, it may be worth trying to apply), http://www.oxygenxml.com/
- XMLMind: exists in both personal (free) and pro (commercial) versions, http://www.xmlmind.com/xmleditor/
- Serna: free and open source, http://www.syntext.com/products/serna-free/
Installing an application is really good only for writing the document, but to have an idea what the document will look like, it is necessary to render it. This is achieved by using DocBook-related tools on the command-line.
Mac OS X
One simple way to install the necessary tools on Mac OS X is to use Mac Ports.
sudo port install docbook-xml-5.0 sudo port install docbook-xsl
Get the required package from repository
sudo yum install docbook5-style-xsl
Files will be in /usr/share/sgml/docbook/xsl-ns-stylesheets/
Once you have the necessary tools installed, rendering is achieved by calling the "xsltproc" command and using some of the available XSL transformation files. Example:
xsltproc --output reference.html /PATH/TO/DOCBOOK/XSL/xhtml/docbook.xsl ~/PATH/TO/DOCBOOK/FILES/reference.xml
The output of the above command is a HTML file which can be viewed simply in a browser.
There are currently very few projects aiming to edit DocBook documents online and most are dead or dormant. As far as we could find during our research the only promising project is the PHP Online Editor. This project is used by the PHP team to work on the PHP documentation (which is based on DocBook).
The hope is to be able to adapt that tool for the TYPO3 documentation. This sub-project has its own wiki page.
There is a very intersting tool used by the Boost project documentation: http://en.highscore.de/cpp/boost/introduction.html
The script be downloaded here: http://www.highscore.de/liveedit.zip
The developer seems available for questions and discussing enhancements (NOTE: francois 17:35, 13 November 2010 (CET) - I have his contact and so does Karsten. It doesn't seem appropriate to put his e-mail address here).