[csw-maintainers] OpenCSW manual

Peter FELECAN pfelecan at opencsw.org
Fri Jan 20 14:23:39 CET 2012

Peter Bonivart <bonivart at opencsw.org> writes:

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

This is the "production form". However Maciej changes quite often the
underlining tool. We had some discussion about this in the past.

>> There is also a version (a stub) compiled to HTML:
>> http://buildfarm.opencsw.org/~maciej/opencsw-manual/
> This looks great.

This is the "consumable form".

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

Is a wiki "source" in the traditional sense? Can it be managed with a
SCM, extracted locally, edited with any text editors? Wikis are great
for some tasks. Maybe not for the one proposed in this thread.

More information about the maintainers mailing list