FAQs Are A Code Smell
July 22, 2019
Summary: Unless you have explicitly ensured that every FAQ has been contextually addressed in your main content, FAQs are a clue that a doc or doc set has organizational problems.
My colleague Joe Medley describes FAQs as a code smell. Wikipedia's definition of code smell is:
... any characteristic in the source code of a program that possibly indicates a deeper problem.
It's not a perfect analogy --- because we're talking about documentation, not source code --- and I don't know if Joe uses the exact phrase "code smell"... but it gets the idea across. FAQs are a clue that a doc or doc set has organizational problems.
I'll never forget the heuristic process that Joe told me he uses whenever he encounters an FAQ. I use it every time I encounter an FAQ too now and --- I kid you not --- it has never failed me, not even once. Whenever you encounter an FAQ, go through each question one by one, and look for a place to incorporate it in your main content. One of 3 things will happen:
- You'll find a much more contextually relevant place to discuss the FAQ.
- You'll realize that your main content is missing this key piece of information that was buried in the FAQs.
- You'll realize that the FAQ doesn't really relate to the main content.
Send me your docs with FAQs and I'll show you, if you don't believe me.
Now, if you're using an FAQ to supplement your main content, I have no problem with that. In other words, if you've gone through your main content and ensured that every FAQ was addressed contextually, and then you provide an FAQ because you know that some readers like the format, then that seems like a good practice to me.
One thing that I do like about FAQs is that it forces you to use the question-answer format. I think this is a powerful rhetorical device that I should probably incorporate into my documentation more.
P.S. I just looked up whether the question-answer format is a literal rhetorical device. Indeed, it is --- hypophora.