Why is the GNU software manual so hard to read?

By | March 11, 2016

I was researching on  what “dnl” meant within a configure.ac file and my Google search showed results from http://www.gnu.org/software/m4/manual/m4-1.4.14/html_node/Dnl.html. Thinking this was the authoritative source, upon reading, I couldn’t for the life of me understand it.

After searching some more, it was explained very clearly and succinctly at Stack Overflow of all places. http://stackoverflow.com/questions/3371239/autoconf-dnl-vs

In configure.ac, lines commented with ‘#’ that occur after AC_INIT will appear in the resulting configure script. dnl comments will not.

20 odd words and I fully understood dnl.

I don’t get it. Is it because:

  • The manuals were written such a long time ago that they need updating because they are irrelevant?
  • Were the manuals written poorly?
  • Are the manuals written at a higher level of understanding and that I, a mere mortal, need to figure it out else where?
  • William Pursell is a really good communicator?
  • Are the manuals more of a technical reference and not suitable for explaining the basics?

In a world where communication is key, software documentation needs to be easy to understand and easy to follow. As they say, the genius is being able to explain something in simple terms because anyone can get carried away with being over technical, over complicated and over complex.


Leave a Reply

Your email address will not be published. Required fields are marked *