PLD Documentation Project launched - creating docs now easy!!!

[Rafał Kleger-Rudomin]

Hello,

I've just run new documentation framework to simplify
the task of creating and maintaining documentation.

Writing, improving and enhancing docs will be easy now
for anyone who has CVS rw access

Project lives in 'PLD-doc/doc' in repo.
This directory contains docbook sources and scripts to process it
Simply 'checkout' the directory if you want to participate in writing 
or improving docs.

The result of convertion to HTML is avaliable here:

http://team.pld.org.pl/~klakier/doc/

and is updated hourly (based on cvs current content)


WHO CAN PARTICIPATE
===================

Everyone who has CVS rw access is strongly encouraged
to write or improve documentation. Depending on
your will and docbook knowledge, you can participate at
different levels:

a) basic level 
   Fixing typos, orthography, style, basic corrections.
   No docbook knowledge is required, just edit document
   and commit it as usual.
   As long as you do not modify document structure there 
   is no need to validate it.

b) normal level
   Translating, enhancing existing docs, more substantial changes.
   Validation is required before commiting to repo.
   See README file in PLD-doc/doc

c) maintainer level
   Creating new documents, adding new translation
   Installing all processing tools is recommended to check 
   the integrity of the project after changes
   See README file in PLD-doc/doc


ANTICIPATED FAQ
===============

Q: 'Devel' docs are located together with 'user' docs, why?
A: This module is intended to be 'flat' collection od documents
   of different kind - just a infrastructure for developing
   docs. Some of them may be then incorporated into PLD www 
   developer corner, other may be presented somewhere else. 
   Moreover, this doc system is not resticted to contain only 
   PLD related docs - if you want to put another document here 
   (for example a manual for software program you develop), 
   please contact me

Q: The html output is ugly!
A: This is only raw html view converted with Norman Walsh stylesheets.
   It is done only for draft visualisation of current documentation effort.
   No customizations, decorations are applied.
   For the time being it is most important to write and improve docs
   not to bother with beautifull presentations.
   
Q: What about coversion to printable formats?
A: None, so far. Investigation in progress...

Q: Why install/en/install.docb is in polish? 
A: It's only placeholder, for testing purposes

Q: Some docs are not up-to-date...
A: Please update them! I currently work on XEmacs docs, some other
   needs update too.


MORE INFO
=========

   See README file in PLD-doc/doc


Regards,
Rafal


-- 
Rafał Kleger-Rudomin (klakier at pld.org.pl)