Re: Building prog first

[Reuben Thomas]

On 21 March 2010 11:40, Ralf Wildenhues <address@hidden> wrote:
> * Russell Shaw wrote on Sun, Mar 21, 2010 at 11:18:03AM CET:
>> But it is somewhat big, and i had already searched through the online
>> one a lot first. It is no wonder it takes noobs so long to get productive.
>
> I'm not sure how to help that.  If more documentation makes people less
> likely to look at it, then what would you suggest in order to improve
> upon the situation?  Is the documentation not structured well enough?
> Does the "Autotools Introduction" chapter in the Automake manual not
> help get a basic grasp?
>
> I agree that the initial learning steps may not be easy for Automake,
> but I don't see how to make Automake a lot easier without also ripping
> out much of the functionality.  So turning that knob is fairly unlikely.

I must say that this is a problem for me with many GNU manuals:
Emacs's comes to mind as well as most of the autotools' documentation.
I struggle to put my finger on what is wrong: one of the nice things
about GNU manuals compared to many other pieces of documentation is
that they are on the whole comprehensive, and everything is
beautifully and clearly explained, with few missing bits, in properly
written sentences. And yet, when trying to learn new things even with
packages I'm quite familiar with (any of the above, for example), I
often end up feeling that I'm in a twisty maze of documentation pages,
all alike. I chase references, I try searching, I go round in
circles...

Usually, the best way out, I find, is to do a web search.

I have a couple of suspicions:

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. Proprietary manuals
seem to suffer from the same problems (I think of similar feelings I
get from perusing Microsoft Office help, for example).

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:

4. I don't know how to do that, and the current format is tried and
tested for a good reason: it works well either when one tries to learn
a system comprehensively, or when one knows a system inside-out but
needs a reference.

In conclusion I'd say:

a) Users: use a search engine.

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.

c) Researchers: More Work Needed. (Or possibly I've just not heard of
the amazing research that has already been done, in which case: More
Marketing Needed.) GNOME's Project Mallard is the only real-world
software I've come across that seems to be an attempt to solve this
problem, but then it's far from obvious that new software is actually
needed, as opposed to simply new ways of structuring and using
documents (i.e. it may be a problem best solved in "human software"
rather than "computer software").

-- 
http://rrt.sc3d.org