[OpenCA-Devel] Documentation

[Michael B. <mic...@cm...>]

Hi all,

aside from the bugs and missing features it looks like the documentation 
is the biggest problem (like for the most Open Source projects). We have 
an OpenCA guide and there is a first structure for systematical tests 
(attached) but the docs are sometimes outdated, really difficult to 
manage and the users cannot update the docs if they find a mistake. So 
what can we do to improve the docs?

I think the most important step is the integration of the documentation 
in the CVS and make infrastructure. Is it a good idea to create the 
following structure?

openca-0.9/doc/test/  - stuff of the attachment
openca-0.9/doc/guide/ - OpenCA guide
openca-0.9/doc/scripts/ - here we could place operational scripts and 
how to operate a ca (perhaps we should call it howto/)

The test stuff is completely latex. The OpenCA guide was written with 
texmacs but it exports latex too. We have to rework the code a little 
bit but I think it is a good idea to switch from TeXmacs to pure latex 
to make it more compatible and easier to maintain by different people. 
This directory includes also the lifecycle image (tex-source). The third 
directory should be used to store examples like Harald's installation 
instructions or some operational scripts which describes step by step 
what a admin has to do if he wants to handle a request. Every howto or 
script set would get it's own directory.

Any comments please?

Michael

P.S. after this we could reorganize the OpenCA guide :)
-- 
-------------------------------------------------------------------
Michael Bell                   Email: mic...@cm...
ZE Computer- und Medienservice            Tel.: +49 (0)30-2093 2482
(Computing Centre)                        Fax:  +49 (0)30-2093 2704
Humboldt-University of Berlin
Unter den Linden 6
10099 Berlin                   Email (private): mic...@we...
Germany                                       http://www.openca.org