Documentation formats

We were discussing documentation formats today within the team, and I have to admit that personally I don’t have a preferred format. I find I use the HTML (online) formats often when I'm looking for something specific, and the PDF when I want to read something in more detail. As I spend most of my day in emacs when programming, I use either HTML or the Info format.

Obviously, with access to the source files, I can also look more closely at certain elements—for example, I like to look across the various chapters when I'm looking for a command or other text, when sometimes accessing the raw source can give me the exact info I want.

We're already working on some ways to improve the way the documentation generated—my last work was part of that. We're experimenting with better linking on the HTML and PDF documents, improved searching, and thinking of ways in which we can provide more specific (and less weighty) manuals.

As a reminder, we already provide HTML (online and download), CHM (download), man pages and, through product releases, Info format (for use in emacs and other tools).

I'd be interested to hear what formats people prefer—do you use the Mysql .info manual within emacs? Is there a format you use that we don't support? Any other improvements you'd like to see?

License

Verbatim copying and distribution of this entire article are permitted worldwide, without royalty, in any medium, provided this notice is preserved.

With thanks to Perth Counselling to keep FSM editors sane.