[csw-maintainers] OpenCSW manual

[Peter FELECAN]

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