The first step was to define what constitutes "official documentation". Anybody is free to publish a manual so we felt a need to define what makes a document "official". The conclusion we came to is that an "official manual" is a manual that has gone through a peer-review process by the Documentation Team. This ensures that such a document is relevant and up to the standards defined by the Documentation Team as much as possible. Official manuals will be marked as such on their cover page (see attached image).
On top of this "seal of approval" we defined three large document categories to make it easier for people to find the right kind of manual. The categories are the following:
- Core manuals which provide in-depth information about a particular TYPO3 Core process, how it is implemented, a reference to its API, etc. (extension keys: doc_core_*)
- Guides are designed to provide a working knowledge of a particular process and be a reference tool for daily work (extension keys: doc_guide_*)
- Tutorials are step-by-steps instructions covering a particular topic (extension keys: doc_tut_*)
These categories are described more fully in the Official Documentation wiki. Thanks to Bill Tenny-Brittian for his help on defining and explaining the categories.
The next step was to discuss a document's structure. Indeed it seemed necessary to give official manuals a more strict structure in order to ensure that relevant information would not get forgotten. As such the cover page was redesigned with the above information (see attached image) and the "Introduction" chapter was precisely defined. It will now always include the following elements:
- a short description of the manual (About this document)
- a brief overview of what has changed in the latest version (What's new)
- credits (in particular the actual authors, since the cover page now only mentions "Documentation Team")
- information on how to give feedback about an official manual
Official manuals will now also have a closing chapter entitled "Next steps" where the reader will be pointed to additional resources to continue improving his or her knowledge. Inside the document itself call-out boxes have been defined that will make it easier to highlight a given piece of information (see attached image).
Finally it was time to wrap it all up with some little refinements. It all started with a couple of small enhancements and snowballed into a major redesign of layout itself. Actually the title of the mailing list thread where all the action happened was "Small improvements to official documentation template". At the end of the day nearly every aspect of the current template had been touched on. Here is an insight into the major changes:
- the fonts were changed to use some beautiful open source fonts (thanks to Jigal van Hemert for the pointer). A serif font is now used for the body text, which makes it easier to read.
- all colors were dropped from the headings
- indents were added to enhance the visual structure of the documents
- the cover page was completely redesigned (thanks to Hermann Ragaller for very constructive suggestions)
- page header and footer were also cleaned up (no more double logo)
In general many people contributed with opinions and advice in a very constructive atmosphere. This was community involvement at its best, thanks to all those who participated. I hope you will appreciate this new design. The first manuals to use it are in the pipeline and will appear very soon.