Summary: “The Problem with FAQs in Documentation” by Tom Johnson

Frequently Asked Questions (FAQs) are not Frequently, nor Asked, nor Questions. According to Tom Johnson, FAQs are annoying and a bad idea.

FAQs start out as a collection of random thoughts someone on the team has about the software. These questions do not need to be about the use of the software, some may be better served in an “About Us” Section. Once testing starts, more input from actual users leads to more questions cluttering the FAQ. After launch is when companies should be making FAQs, but this time is when the team doubles the section. Where this leads is a monolith of “documentation” that is unmanageable and unhelpful.

Much of Johnson’s critique of this model in the first section is on the effort it requires. An important quote is “The team member…cranks out quick responses to these random questions with about the same effort as typing an email.” From the standpoint of a technical writer, this is not the correct way to write documentation. The proper way, in Johnson’s opinion, is to analyze the user’s goals and weave them into a story-like structure.

This is something that the FAQ format ignores, and is one of the main points in the second section. Proper documentation should start with a goal and provide a walk-through on achieving it. This would avoid Johnson’s second complaint, which is: As the list grows, it becomes less manageable and ruins the user experience. This is a direct consequence of throwing all questions together into one list, as he says, “…the trivial questions dilute focus from the more important questions.” Point four says that the questions are only miscellaneous questions, while point five points out how they are rarely from the actual users.

Combining all these points shows the following: the questions are not frequent, as they could have occurred once (or not at all); the product team could have imagined them, meaning they were not asked; and because the product team wrote them, they aren’t even questions.

The reason that product teams use FAQs instead of proper documentation is because they are easy to write. In this section, Johnson ties back to the point he made in the first – the effort required for FAQs is not enough for actual documentation. He also suggests a pattern to use instead of the Question and Answer pattern: Goal and steps required to accomplism it. This goal-driven narrative is required for proper documentation, but as Johnson states “…the difference is that the answer to these goal-oriented questions will entail a heck of a lot more information and detail than the random FAQ,” which is something that project teams may not want to invest.

Overall, Johnson believes that there should be a switch from FAQs as documentation to user stories in the form of goals and steps. FAQs can be added after the actual documentation, but if a question makes it to an FAQ, the actual documentation should change to account for it. FAQs should be reserved for 5-10 questions that are frequently asked by users – not places to put the story of your company.

~ Connor Shade

Advertisements

About cnnrshd

Computing Security student @rit