automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

better documentation (was: Building prog first)


From: Ralf Wildenhues
Subject: better documentation (was: Building prog first)
Date: Sun, 21 Mar 2010 19:49:17 +0100
User-agent: Mutt/1.5.20 (2009-10-28)

Hello Reuben,

* Reuben Thomas wrote on Sun, Mar 21, 2010 at 07:32:32PM CET:
> 1. This is not a fault especially of GNU documentation; rather, GNU
> documentation is one of the few places in free and open source
> software where one finds properly written manuals.

Nice to hear!

> 2. I suspect the problem is to do with structuring, but I'm not sure
> how to solve it, except:
> 
> 3. Since search engines largely bypass the problem, it doesn't really
> need to be solved. However, manual authors could possibly aid the
> process by writing documentation that is more "searchable", only:

Good indexing is one way to help that (I would hope).

Here's an advice for new users: If you have words or phrases that spring
to mind when you look for something, and don't find it by those words in
any of the indexes (indices?), then please write to bug-automake about
it.  I'm all for adding more index entries.

> b) Developers: keep writing proper manuals for now. However,
> well-written responses to mailing list questions are particularly
> valuable, as are FAQs and cookbook-style documentation based on
> real-world uses.

Well, we certainly have too few FAQ entries.  Suggestions for more are
welcome, too, but I'm usually slow to write them and picky to accept
text.  ;-)

Thanks for your suggestions,
Ralf




reply via email to

[Prev in Thread] Current Thread [Next in Thread]