Documentation formats

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?

Category: 

Author information

Martin Brown's picture

Biography

Martin “MC” Brown is a member of the documentation team at MySQL and freelance writer. He has worked with Microsoft as an Subject Matter Expert (SME), is a featured blogger for ComputerWorld, a founding member of AnswerSquad.com, Technical Director of Foodware.net and, and has written books on topics as diverse as Microsoft Certification, iMacs, and free software programming.