Re: [GNUe] GNUe and beginners

[Adrian Maier]

On 10/23/06, Reinhard Mueller <address@hidden> wrote:
> 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
> Then we switched to Lyx
> Then we switched to Docbook
> Then we switched to OpenOffice 1 format

Ouch... I had no idea that the list of the formats that have been tried
is so long.

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

Well, in order to get help the first step is to have enough
non-developers  that
have sufficient knowledge so that they can write documentation.

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

It looks like this choice is made ...

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

Hmmm...  The API reference is of interest only for the gnue developers ?

What do you mean by "user" ?  final-users, or
developers-that-build-applications-with-gnue ?



--
Adrian Maier