Re: A Closer Look at GNU AutoTools

[Shawn H Corey]

On Thu, 4 Sep 2014 17:55:27 -0400
Nick Bowler <address@hidden> wrote:

> On 2014-09-04 17:00 -0400, Shawn H Corey wrote:
> > On Thu, 4 Sep 2014 16:33:13 -0400
> > Nick Bowler <address@hidden> wrote:
> > > Can you be more constructive?  I think Autoconf and Automake have
> > > rather good manuals[1][2].  Why are they crappy?  How can we make
> > > them better?
> > > 
> > > [1] https://gnu.org/s/autoconf/manual/autoconf.html
> > > [2] https://gnu.org/s/automake/manual/automake.html
> > 
> > When was the last time you read completely through those manuals?
> > There's too much information all at once.
> 
> I have never read the manuals cover-to-cover.  But by now I have
> probably read most, if not all of the material in them over the
> course of ~10 years.
> 
> But this puts me in a bad position to critique the manual from the
> perspective of newbies: as I know Autoconf rather well I am unlikely
> to notice if some details are missing from the manual.

It's not that it's has errors or it lacks detail. The problem is it has
too much detail. When it presents a topic, it present all possible
variations of it. But most of those variations are not needed by the
average developer.

> 
> > And I didn't say the manuals were bad. It's that the documentation
> > is too dense and not organized for learning. In other words, crappy.
> 
> Sorry, I am having a hard time reconciling these two statements.

That's because you have forgotten what's it like to be faced with
thousands of pages of technical manuals about something you know
nothing about and all you want to do is a simple task.

> 
> > It took me two days to find the diagram on my blog from Wikipedia.
> > It should have been one of the first things I searched for.
> 
> Similar diagrams are found at the very beginning of chapter 3 ("Making
> configure scripts") of the Autoconf manual.  Would changing them or
> perhaps adding another diagram here improve the manual?

You mean those ASCII diagrams that should be inside <pre></pre> tags?
And you don't think that's crappy?


-- 
Don't stop where the ink does.
        Shawn