[csw-maintainers] OpenCSW manual

[Maciej (Matchek) Bliziński]

2012/1/20 Peter Bonivart <bonivart at opencsw.org>:
> 2012/1/20 Maciej (Matchek) Bliziński <maciej at opencsw.org>:
>> Hello maintainers,
>>
>> Dago and I talked recently about the next generation of OpenCSW
>> documentation. Dago's take on the topic was that there are 3 key
>> audiences that our documentation needs to address:
>>
>> 1. System administrators
>> 2. Developers
>> 3. Package maintainers
>
> I think it's great to target the different audiences like that. Will
> make it much more clear when reading.
>
>> I experimented with Sphinx, a tool which allows to compile
>> documentation written in reStructuredText into HTML, epub and other
>> formats. I've prepared a stub and put it into pkg/opencsw-manual.
>>
>> https://gar.svn.sourceforge.net/svnroot/gar/csw/mgar/pkg/opencsw-manual/trunk/
>
> This looks horrible.

Really that bad? The most realistic example is this one:

https://gar.svn.sourceforge.net/svnroot/gar/csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/shared-libraries.rst

I challenge you to write this document in any other markup that will
look better than this! :-)

>> There is also a version (a stub) compiled to HTML:
>>
>> http://buildfarm.opencsw.org/~maciej/opencsw-manual/
>
> This looks great.
>
> Why not document on a(ny) wiki which is made for ease of
> documentation? Where I work every document system failed until we
> implemented wikis, now people from all areas document new stuff and
> keep it updated just because it's so easy to do so.

I agree that source code repository is harder to modify than a wiki.

I agree that wikis are better for general documentation, such as GAR
variable reference. The stuff that can change quickly and needs to be
very easy to update.

While wikis are good for vast knowledge bases, they don't allow for
reading top-to-bottom. The idea behind the manual is that it's an
introductory material for newcomers, which you read once,
top-to-bottom, and it gives a basic understanding of what you're
dealing with. The manual must not be large, each of the 3 sections has
to be possible to absorb in one evening.  If we have a newcomer, we
point them at the manual, and this should be enough to get anyone
started with the project (from each of the three perspectives).

Thoughts?

Maciej