The official documentation for V3 is to be published at our docs site: http://docs.fckeditor.net
The documentation will be grouped in the following way:
- Design and Architecture: the dissection of the building blocks of V3.
- Developer's Guide: installation, configuration and customization information for developers using V3.
- User's Guide: full user interface instructions for end users.
Other than the official documentation web site, we aim to provide the complete documentation in separate downloadable files.
We should support the following distribution formats:
- Browsable HTML: a series of HTML pages;
- CHM: the Microsoft help file format, preferred by Windows users for being a single browsable file (like a mini site) and searchable;
- PDF: for good quality printing and reading.
Much probably, the best solution would be exporting our docs site contents to the DocBook format. In this way it would be easy to automatically build the documentation in other formats.
The documentation site must be prepared to handle the translation of the official documentation. Translations must provide the same quality and efficiency of the original.
Documentation is a big and exhaustive task. But it's also one of the most important things in a software project. Therefore, specialization is needed to well organize it, producing high quality results.
This is an important role. The Documentation Manager has a complete overview of the project documentation. S/he must also have in mind the overall objectives of it, and how it impacts in the development process.
Even if the Documentation Manager may also write documentation, this is not his/her main task. S/he must actually direct its development and control its quality, by monitoring changes. S/he is also the reference for other documentation contributors.
The Documentation Manager is someone with good knowledge of usability and management.
All contributors are invited to write documentation, but some of them are specialized on it. They know all writing standards of the project and produce quality texts.
English Documentation Reviewer
Being English the main language in the project, we must provide standard and high quality texts in that language. Therefore, we must have a good English writer ready to review all texts introduced in the documentation.
It is important to remember that this project is maintained mainly by non-native English speakers.
Documentation Translation Manager
This is a "per language" role, which guarantees that the translation offers the same quality as the original.
Documentation Translation Reviewer
As o rule of thumb, every translation must be reviewed by someone else. So, theoretically, we must have two reviewers for each language (one of them may be the Document Translation Manager).
We'll be using in code comments to document our API. In this way we also provide quality references for developers navigating through our code.
For V3 we'll be basing our code documentation on the JsDoc Toolkit features.