Wandering Thoughts archives


The two (at least) forms of documentation

The problem with GNU Texinfo is not that it is a bad format for documentation as such. The problem is what sort of documentation gets written in GNU texinfo format.

To simplify, there are at least two forms of documentation: tutorials and references. Where I draw the line between the two is that is that tutorial documentation is intended to be read from start to finish, while reference documentation is intended to be skimmed and skipped through.

Writing something as a tutorial has at least three effects that are relevant here:

  • it is perfectly sensible to scatter information about something across several places; it is more important to have the entire work in a logical sequence when read as a whole than to have all of the information about something in a single place.

  • it's also perfectly sensible to break information up into small chunks, each covering one thing or one concept, and present them independently; it gives readers natural pause spots and avoids confronting them with an endless wall of text.

  • it is not important to have a clear, easily visible organization, as long as everything makes sense and flows logically as you read through the whole thing.

None are good things for reference documentation, where you want everything in one spot, clearly organized even if you don't know the subject and easy to skim and page through as a single unit.

The general problem with focusing on tutorial documentation over reference documentation is that tutorial documentation is used infrequently, to learn the system and to get large-scale refreshers on it, while reference documentation is used much more frequently, when you forget an option or a feature or whatever.

(Tutorials also fall down if your audience is not really interested in your subject matter, because they demand too large an investment of time before you get much out of them. With reference documentation people have at least some chance of getting a specific question answered quickly, before they just give up.)

So the problem with GNU texinfo is that people pretty much only use it to write tutorial documentation, and many of its features are oriented towards this; if you write in texinfo format, there are lots of things pushing you towards tutorials as the most natural outcome. (It doesn't help that the FSF is strongly against manual pages; culture matters.)

tech/TutorialVsReference written at 23:57:30; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.