What FAQs are

April 20, 2008

Here's a question: which type of documentation is the ever-popular FAQ format?

My answer is that in practice, FAQs are a collection of tutorials; they tell you how to do various specific frequently asked operations. This has important implications if your primary documentation format is FAQs, because FAQs effectively have drawbacks from both sides; they're not as well organized or as comprehensive as reference documents, and they don't give you an overall view the way a single unified tutorial does.

(That they are a collection implies that FAQs live and die on their organization, ie how easy it is for people to find the specific question that they need.)

If FAQs are currently your primary form of documentation, I think that the most important second form to have is reference documentation, because it is the most efficient way to cover the remaining information and probably also the easiest for people to use.

(By 'efficient' I mean 'most results for the least amount of documentation writing'. Complete tutorial documentation is almost always longer than equally complete reference documentation.)

As an aside, FAQs as your primary documentation may seem silly, but I think it's a natural thing if you're too pressed for time to write much documentation. FAQs make it easy to create something useful right away and then grow it piece by piece, they give you a natural starting point, and it's less intimidating to sit down to write some FAQs than to write either full tutorial or full reference documentation.

Written on 20 April 2008.
« The two (at least) forms of documentation
Finding the name of your caller in Python »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sun Apr 20 00:34:26 2008
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.