Automake Manuals (RANT)

[Arthur Schwarz]

Well, putting it gently you have a good product and one of (maybe, the)
worst manual on earth describing it. You can’t argue that as a volunteer
effort you depend on volunteers, because you have volunteers willing and
wanting to put their backs to the wheel to improve your manual, e.g.,
http://lists.gnu.org/archive/html/autoconf/2014-09/msg00000.html. My
question is why don’t you use these ready hands or why don’t we see their
result? 

Lest you think that I wail at others without efforts of myself, let me say
“nay”. I am trying to help as best I can by rewriting all of Section 15
Support for test suites. But I don't know Tex/LaTex/Texinfo and my efforts
are restricted to Open Office/Adobe PDF and Open Office generated LaTex
files - and others have commented on their inadequacy,
http://lists.gnu.org/archive/html/automake/2015-04/msg00026.html. 

My forte is in ungrammatical sentences and misspellings (until I grow up and
edit the text), but a very rough draft of my own efforts is given in
http://lists.gnu.org/archive/html/automake/2015-04/msg00028.html. So even
the weakest of your readers is trying to help.
 
Section 15 of your document has grammatical errors, errors in logic and
errors in organization, see
http://lists.gnu.org/archive/html/automake/2015-03/msg00078.html. I have
been asked whether I will/will not include a patch to fix the items, see
http://lists.gnu.org/archive/html/automake/2015-03/msg00087.html. The quick
answer is "as best I can I will include material". Will anyone of the
Automake developers accept it or support me in providing a patch in a manner
acceptable to the Automake community? Just a question.

My fondest hope is that the comments of others, as well as myself, are taken
to heart and that you begin to solicit or perform needed document changes.

art

 
Maintenance turns design into chaos