Re: [GNUe] GNUe and beginners

[Reinhard Mueller]

Hi, Adrian!

Am Montag, den 23.10.2006, 13:11 +0300 schrieb Adrian Maier:
> The chosen format should be text-based (sgml/xml)  so that it will be possible
> to get patches for the documentation ....
> 
> I can't imagine how the users could *ever* help with improving those documents
> if we keep them as openoffice documents .

We have had documentation in Texinfo, and people told us that they would
send us improvements if we used a WYSIWYG program because they don't
understand Texinfo format.

Then we switched to Lyx, and people told us that they would send us
improvements to our docs but Lyx is too unstable and slow so they can't
work with it.

Then we switched to Docbook, and people told us that they would send us
improvements but they don't understand Docbook syntax and XML is too
complex for them.

Then we switched to OpenOffice 1 format (2 wasn't existant at that
time), and people even stopped to tell us that they would send us
improvements.

Now we start to use ODF, which is an approved ISO standard. We have
always made clear that we are ready to accept help for documentations in
any format, and that we will happily do the conversion from any format
we can read. Still, I can't remember when we got any comment on our
documentation other than "it sucks".

Personally, I have given up hope to ever get any help with
documentation, no matter in which format. I have learned (the hard way)
that as a developer, you must write your docs yourself.

So it seems natural to use the document format that the *developers*
prefer. This is quite clearly ODF for all main developers.

> b)  "Core Documenatation" , containing the api (generated from the
> classes ?) and some
>      tech docs.

"Core documentation" is documentation that is of no interest to the
user, but is only targeted at developers of the tools themselves. It
makes sense to keep them separate, IMHO.

Thanks,
-- 
Reinhard Mueller
GNU Enterprise project (http://www.gnuenterprise.org)

signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil