Changes between Initial Version and Version 1 of Documentation

Timestamp:

Jan 23, 2007, 11:03:17 AM (18 years ago)

Author:

Frederico Caldeira Knabben

Comment:

--

Documentation

@@ +1 @@
+[[TOC]]
+
+= Documentation =
+
+The official documentation of FCKeditor is available at:[[BR]]
+http://wiki.fckeditor.net
+
+It is a Wiki site running over [http://moinmoin.wikiwikiweb.de/ MoinMoin] and hosted by the !MoinMoin creators.
+
+Today we have a developer centered documentation, aiming to provide an easy integration and customization of FCKeditor.
+
+== Plans ==
+
+The documentation is about to be reviewed. We must find a good solution considering the following:
+
+ * Better Structure: review the Table of Contents;
+ * Separate "Developer's Guide" from "User's Guide";
+ * Wiki: easy to update;
+ * Distribute in different formats: browsable HTML, HTML single page, CHM and PDF.
+ * Translatable
+
+Other than that, the documentation site will be moved to "docs.fckeditor.net".
+
+=== Better Structure ===
+
+The current Table of Contents must be completely reviewed and well defined. It must be intuitive and easy to use, other than complete.
+
+=== Developer's Guide ===
+
+The "Developer's Guide" is the first reference for those who are starting with FCKeditor, and also for developers looking for advanced features of it.
+
+The reference to "Developer" here, has nothing to do with "Project Contributors". It refers to our first target instead: developers aiming to use FCKeditor in their projects.
+
+=== User's Guide ===
+
+Today, no documentation is available for end users. We must provide a complete help to support the editor usage. It must be easy to use, intuitive, and full of screenshots and attractive graphics.
+
+=== Wiki ===
+
+We believe that Wikis are the best way to create and maintain a collaborative documentation.
+
+Today we are using [http://moinmoin.wikiwikiweb.de/ MoinMoin] for it. We are planning to move to [http://www.mediawiki.org MediaWiki], so we will have better control of the installation. 
+
+We'll be also looking for integrating FCKeditor with !MediaWiki (Wikis in general), so the documentation site will be used as the showcase for this integration.
+
+==== Search ====
+
+The Wiki site, being the main documentation resource, must be searchable.
+
+==== Vandalism ====
+
+In the latest period we have had more vandalism to handle than real contributions. Therefore, our new documentation site will not accept anonymous editing. If this restriction will still not work, editing will be available only for approved users, and the comments page will be left for registered users to add their bits.
+
+Unfortunately, that's the way thinks must be done in this wonderful world.
+
+=== Distribution ===
+
+Other than the official documentation web site (the Wiki itself), we want to provide the complete documentation in the FCKeditor distribution package too. We may also think about distributing it in separate downloadable files.
+
+We should support the following distribution formats:
+
+ * Browsable HTML: a series of HTML pages;
+ * Single HTML page: a single HTML page with the entire documentation. Some people prefer it for because of its "searcheability";
+ * 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.
+
+We believe that the best solution would be the export of the Wiki site to the [http://en.wikipedia.org/wiki/DocBook DocBook] format. In this way it would be easy to automatically build the documentation in other formats.
+
+=== Translations ===
+
+The new 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 ===
+
+Current contributor: ''none''
+
+This is an important role. The Documentation Manager has a complete overview of the project documentation. He/she 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. He/she must actually direct its development and control its quality, by monitoring changes. He/she is also the reference for other documentation contributors.
+
+The Documentation Manager is someone with good knowledge of usability and management.
+
+=== Documentation Writer ===
+
+Current contributors: ''none''
+
+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 ===
+
+Current contributor: ''none''
+
+Being English the first 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 ===
+
+Current contributors: ''none''
+
+This is a "per language" role, which guarantees that the translation offers the same quality as the original. 
+
+=== Documentation Translation Reviewer ===
+
+Current contributors: ''none''
+
+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).