[csw-maintainers] OpenCSW manual

[Peter Bonivart]

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.

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

/peter