FAQs are not the answer

Everybody loves to hate Frequently Asked Questions, or FAQs. More often than not, technical writers pale and stagger at the sight of hefty, unsorted FAQs, as if they were beholding a writhing mass of primal chaos. Others value their pragmatic qualities: FAQs, they say, lower the bar to contribution and are good fuel for LLMs and search engines. My opinion is that FAQs pose a problem only when there’s no strategy around their usage.

Docs’ subconscious is full of FAQs

I wouldn’t call FAQs an anti-pattern or a dark-pattern because both terms entail some degree of consciousness. No, FAQs rarely are a deliberate tactical choice; most of the time, they arise from the urgent, irresistible need of dumping pressing questions and their answers somewhere visible, which doesn’t necessarily mean accessible. FAQs in websites are the little death of content strategy: amorphous blobs of content left to wander in the backrooms of the web.

Why is that a problem, you wonder? After all, those are useful answers to important questions. Let them be! Well, that’d be a considerate thought were it not for the poor UX that mindlessly FAQing around can cause. As Tom Johnson states in The Problem with FAQs, FAQs are messy, don’t scale well, and they often originate from concerns that don’t come from users. Hard as they are to maintain, FAQs end up reading like hastily composed laundry lists.

FAQs are readily available in our mind because we keep seeing them everywhere, much like README files. They’re relatable and easy to understand, and thus easy to recommend. Being to content types what a colony of unicellular organisms is to animals, FAQs can’t really grow and be sustainable. They lack specialization and structure, which are essential to documentation that needs to build up product truth.

To build a good FAQ, don’t build an FAQ

In perhaps the greatest plot twist of all times, the venerable Nielsen Norman Group, the mogul of UX, considered FAQs to be worth the effort, which perhaps explains why they maintain a surprisingly traditional FAQ on their website. This cunning move, I’m sure, reassured hundreds of webmasters that sought NN’s advice and wanted not to feel like content sleepwalkers. There’s a catch, though: in their piece, NN emphasizes that good FAQs are structured. They need a lot of thought to be done well.

NN’s advice, which seemingly ignores decades of information architecture and content typing, should be read as follows: FAQs originate from a valid drive, which is addressing internal and external needs with useful, actionable, and concise information. This, however, doesn’t mean that you can just release a dumpster fire of questions and answers in your docs. Rather, you should build a strategy around that instinct to create structured, reusable, indexed content, like Troubleshooting docs.

Even platforms that actively promote FAQs seem to acknowledge their limitations. For example, Mailchimp’s How to Create Effective FAQ pages, after praising FAQs because they’re good for SEO, gingerly drops this recommendation:

A well-organized FAQ page has structure. Your FAQ page should have an information hierarchy that makes sense. You can review FAQ page templates or create your own for different question categories or products, depending on the layout of your website.

Which is to say to build a good FAQ, don’t build an FAQ. Just use the FAQs as building blocks.

What to do when you feel the urge to FAQ

There it goes: a customer pressing question makes its way to the documentation channel of your company. Someone suggests adding a question and its answer to a doc, perhaps an FAQ section somewhere. Folks will find it, search engines will rejoice, and support will have something to link to, even if it’s just a fragile question lost in the middle of other unrelated doubts.

That’s the moment where, as a tech writer, you must stop and intercept the thought of creating an FAQ. The goal isn’t to eradicate question-and-answer formats from the face of the planet (that’d be cruel), but to ensure information is organized thoughtfully and sustainably. After all, great documentation answers questions before users even need to ask them.

So, instead of FAQing things up, consider any of the following alternatives:

• Reformulate the question as reference or prescriptive documentation, find a location for it, and integrate it into your existing docs. For example, instead of adding “How billing works for tokens”, create a topic that describes how billing works that you can integrate into your existing information architecture and expand later on.
• Create a reusable template for troubleshooting sections at the end of your procedural docs. This helps tie related information together and facilitates the consumption of technical workarounds for a specific feature. There’s a subtle yet important difference between stamping a question somewhere and presenting a solution to a problem.
• If you think this question-and-answer dynamic can help you get more contributions to your docs, shepherd them into a purpose-built section of your docs, like a knowledge base. This accomplishes three goals: it lets contributors continue sending inputs, it provides a structure and UX that can evolve independently, and it keeps the rest of your docs FAQ free.

Great technical writers use FAQs as a starting point to identify and fix gaps in documentation, much like great therapists reflect questions and lapsus back to their patients in a more structured form. Therapists don’t simply answer questions: they help clients see the broader patterns and structure behind their concerns. More on this in another post.