Every once in a while I come across one of the GNU Info manuals. And every time I do, I get the same strange feeling of how clear and on-point they are written. I read a lot of documentation. Info manuals have a hard-to-grasp quality about them that just make them stand out of the crowd.
I find this very interesting because Info manuals are existing somewhat in the shadows and have an arguably archaic appeal to them. They are a marriage between hypertext and man pages with minimal markup. I guess barely anyone outside of the GNU project knows how to write the markup for Info manuals, and I have never seen an Info manual outside of GNU or some project tightly associated with GNU software.
Still, you can find quite some of those manuals at GNU. After all, this is actually the offical documentation system for GNU projects. Mind that these manuals are usually targeted at a very technical audience. Also, I do assume that not every Info manual is the same level of quality. In case you want to take a look yourself I can recommend the glibc manual and the Emacs manuals. Being some of the most high-profile GNU projects, these are probably also some of the best maintained manuals.
While you will be able to read them in a browser, you will loose some of the real Info experience™. Info manuals are more akin to epub and basic html than the documentation webpages you are likely used to. They are meant to be rendered in different styles, formats, software and devices. Arguably, a specialized Info reader is the best way to consume them. You’ll get to choose the presentation style, get some “bookshelf” functionality, full text search and probably the best index search I have ever seen. There’s a standalone info reader and one integrated in Emacs. There is however quite some learning curve to even use them (at least for what they are).
I really have no idea who is writing those manuals. I kinda doubt it’s professional tech writers to any significant degree (if at all). And given that they must be written by different people, I cannot tell how they manage to be so consistent—at least within and across high-profile projects like glibc and Emacs manuals. Maybe by now it is some kind of self-perpetuating culture. Once other manuals of high quality are written, others just follow suit. Maybe there should also be a Pretty windows theory.
I wished I would have a set of easy-to-follow rules what they are doing right, but I don’t. There are also already plenty of guidelines available. I don’t believe it will ever be possible to mechanize this. One rule that is quite obvious and which I want to emphasize: they do not try to cater to every audience in existence, at the same time, in the same text. This is one of the penultimate sins I see in so many tech books.1
Nevertheless, while it might not be possible to just follow some rules, I do believe it is possible to learn from examples. It takes intuition and a certain knack for language. Also, I think the best way to learn is to actually experience the manuals yourself, e.g. when writing a C program or using Emacs/Elisp. For example a reference manual is best if people
- find all the information they need
- not an ounce more
- when they need it
- where they need it
- in the least amount of time
- with the least amount of effort
- and the least amount of mental overhead
The holy grail of course is how to do this. Also, not every manual is a reference manual. Not every manual is for experts. And then there’s also everything in-between. It’s more art than technique. We can only strive to get better over time, learning from others.
No. Also you cannot write a book that is equally useful for beginners and experts alike. Just stop this. If I read this in introductions I immediately know it is either annoying to experts, too hard for beginners or somewhere in the middle making everyone unhappy (except for people in the middle of course). It’s just one book, a largely one-dimensional text. It is not a multi-dimensional direct-text-to-brain interface. It. Does. Not. Work. Know your audience, write for them. ↩︎