Latest revision as of 02:38, 22 February 2008

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.
• Developer's Guide / API: details about our JavaScript code API.
• User's Guide: full user interface instructions for end users.

Distribution

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.

Translations

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.

Contributors Roles

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.

Documentation Manager

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.

Documentation Writer

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).

JavaScript API

Being V3 strongly plugin based, we'll be also pushing our community to provide their own plugins. Developing plugins must be a lot of fun, and to provide this enjoyable experience, we have to well document our JavaScript API, as this is the point of interaction between plugins and the V3 framework.

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.

There are no precise standards for in code JavasScript documentation. There is though a tendency on sticking to the comments format proposed by JavaDoc, the in code documentation format for Java. The most well known and successful project providing build tools for such format in the JavaScript world is the JsDoc Toolkit.

For V3 we'll be basing our code documentation on the JsDoc Toolkit features.