Development Process Technical Communications

7 Reasons to Start Publically Documenting Your Product

If you sell a product, it’s your job to make sure people can RTFM. Stop joking about product documentation and start doing it right.

Any product that needs a manual to work is broken. (Elon Musk)

A user interface is like a joke. If you have to explain it, it’s not that good. (Half the internet)

You’ve probably seen one or both of these quotes circulating at some point. They’ve both had vast appeal. And they sound true, don’t they? I’ve seen them shared by plenty of tech industry people, and I have to admit that this makes me both a little sad and a little mad.

It seems quite a few companies have bought into the idea that their products are so simple and brilliant that no docs are required. This is true for almost none of them.

Most products without documentation are not works of genius, they’re just systems that are harder to use than necessary. A complicated user interface can actually be very good once you’ve learned it—just ask any geek who swears by the command line.

If you don’t have proper, public, searchable product documentation, it’s time you started.

Here are 7 reasons why.

1. Solid Documentation Makes Everyone’s Lives Easier

If you don’t have public product documentation, I am willing to bet you have a lot of unofficial documentation floating around your various departments.

This internal documentation comes in various formats, and different people will hold on to different versions of the same document without knowing other versions exist. Customer support will struggle to get the information they need about the product. They will also piece together their own documentation based on what they hear and find. They may or may not share that documentation with customers.

Everyone will benefit from having a proper documentation process, even internally.

I believe tech writers should be embedded in development teams if at all doable. They should also stay close to User Experience and Customer Support. Their documentation will not come out as marketing documents, elearning, webinar presentations, or scripts for customer support.

What this documentation can do, is:

  • Act as a reference point and source of truth for almost everything else you want to produce.
  • Help with internal alignment and lessen the risk of people further removed from product development guessing or making stuff up.
  • Simplify onboarding for new employees or employees transitioning to new roles.

In the age of “content”, there is much talk of making the most of the content you have, repurposing and publishing across channels. Documentation is an excellent and natural starting point.

If you get into DITA or other structured data formats, you can even repurpose content directly. I have yet to drink the DITA kool-aid, but would love to see more easily accessible systems for single-sourcing.

2. People Need Searchable, Scannable, Skimmable Text

Video and webinars may be popular, but when you need to perform a procedure you only do once in a blue moon and have never fully memorized, you probably want a scannable, written procedure with steps in it.

While working with elearning, I once saw a colleague save a series of screenshots from an elearning sequence so that they could recap the steps on demand without sitting through the course. Even elearning pros don’t  like it that much.

It’s also not enough to put guidance inside your user interface. The most brilliant explanation next to a setting will do me no good if I do not know where to find that setting (or why I should look for it in the first place).

I have recently spent a lot of time with Odoo, an ERP system that also does CRM, ecommerce, and a bunch of other stuff. For a system that does so much—and rather well, most of the time—it has a shockingly small amount of product documentation.

Instead they have chosen to create “setup wizards” in their interface. These wizards contain mostly general project and marketing guidance and very few instructions on setting up the software itself. They must have spent massive amounts of time pouring tons of this irrelevant text into their user interface. They also provide elearning videos on some topics, and some very brief user documents, and that’s about it. (Their developer documentation looks a lot better, although I’m not the best judge of that.)

I have spent countless hours searching in vain for basic configuration guidance and having discussions with consultants and customer support who also don’t have documentation to refer to. And I am convinced everyone’s time could have been so much better spent.

3. Text Is The Easiest Format to Maintain

One theory I heard from a consultant about why this company had so little documentation, was that it would be hard to maintain, and that’s an argument I hear quite a bit about documentation.

Having maintained all of the above-mentioned genres at some point, I can safely say that yes, maintaining a large documentation set is indeed a lot of work. But properly version controlled, text-based documentation is far easier and cleaner to maintain than elearning, videos, and elaborate in-product wizards, especially for a complex product.

Don’t use “it will be hell to maintain” as an excuse not to document your product.  Use it as motivation to start your documentation off right:

  • Pick a sensible, text-based source format (yes, this leaves out MS Word) and version control everything.
  • Hire an experienced technical editor / writer to own the docs and the process as soon as you can afford to.
  • Don’t outsource any of this unless you actually do want a maintenance nightmare.

4. Having A Documentation Process Will Improve Your Product

Here’s a tech aphorism I prefer to the manual jokes: If I can’t document it, people can’t use it.

Tech writers tend to team up well with Quality Assurance, for several reasons. For one, most QA people have fabulous product knowledge. Also, good tech writers poke holes, report bugs, and play user advocate, much like good QA people.

Having to document flows and procedures in full can be a very effective way of highlighting shortcomings and over-engineering. (I remember saying “are you sure you want to have three separate tools for this migration process?” and, fortunately, being heard.)

5. Your (Power) Users Will Love You For It

Leah Guren of Cow TC, who I’ve had the pleasure of listening to on several occasions, is one of few who has done usability studies specifically on documentation.

Guren found that the typical “amateur” user assumes that documentation exists, and that it is pretty much perfect. However, there is almost nothing in this world that can make them voluntarily turn to the help documentation.

Advanced users, on the other hand, would use and rely on documentation, and would be willing to leave a vendor if their documentation wasn’t up to snuff.

6. They May Even Help You

I actually asked my contact at Odoo where I could sign up to help with their documentation … I know I am not in the least typical, and most users are not current or former tech writers, but if you have a user base, by all means solicit participation.

By gathering feedback and analytics on product documentation you will also get new information about the needs, questions, and frustration points of your users.

7. Ultimately, It’s Your Job

Administration of several complex systems is part of my current job. I am constantly looking things up, and nothing makes me happier than finding up to date, official documentation that meets my needs.

By all means, I will be happy with a thread on a forum when it actually answers my question. But if you’re a product vendor—why on earth would you leave it up to random people on third party sites to make sure your users know how to use your product?

Proper product documentation is your job, dammit.

Technical Communications Writing

No, You Don’t Need An FAQ. FAQs Must Die.

I’ve never been on Jeopardy, although I watched it on occasion when it was still running in Norway. As much as I enjoy trivia games, this was never a favorite of mine. The “answer must be a question” rule leads to lots of contrived questions, and contestants get eliminated for not remembering the “Simon says” aspect, even if they know the answer.

I’m A Writer, Not A Jeopardy Contestant

When you write for an FAQ, you take out the fun factor and big prizes, but keep the stilted and awkward aspect. No matter the topic, you have to turn everything into a question.

I will take most format challenges anytime: I write text for graphical user interfaces, I follow patterns when documenting procedures, I tweet. Then again, those are all exercises in conciseness, and I love concise, especially in technical communications.

The frequently asked questions format seems concise enough; an FAQ section is usually built up of small, discrete topics.

But in my experience, the opposite is true. From both a writing and reading point of view, I find FAQs to be contrived, redundant, and inefficient.

And that is why FAQs must die.

The UK Government Digital Service has made a fantastic case against the format in FAQs: why we don’t have them.

1. The FAQ Format Is Contrived

The biggest FAQ I ever worked on was a poorly defined database of articles meant to cover everything people couldn’t find in the general documentation. Yes, I admit it had plenty of issues alongside the question format.

The writing team had previously agreed upon an FAQ format, but many of the best entries still had titles that were scenarios, as these articles were often written for troubleshooting purposes.

Imaginary example: “My client times out when trying to connect to the load balancer.”

A helpful colleague, realizing that these couldn’t be read as questions, decided to go through the whole thing. At each scenario, they would toss in full stops and a “Why?” at the end to fit the format where needed.

“My client times out when trying to connect to the load balancer. Why?”

Every time I saw one of those titles, the “why” would take on this whiny, accusatory tone in my mind. It may not have read very well, but my colleague was doing the right thing entirely, both for the sake of consistency and for demonstrating the shortcomings of the format.

In the end, we agreed that we would call it a knowledge base rather than an FAQ and drop the question requirement. We even got a few other publishing guidelines implemented.

By all means, create a knowledge base if you need one, but define it well and don’t force a question format.

2. FAQ Headings Are Redundant And Unscannable

When you turn headings into questions, you add filler words, and you mostly lose the opportunity to frontload—putting the most significant words, the keywords users are actually looking for, first.

The same thing goes for “how to”-style titles, even when there is not a question mark at the end.

To see what a poor idea this is, try listing several of these headings after each other as they would be in search results or an index. What you get is a list that has low scannability and lots of redundancy, which is not what anyone wants in a list. (I have written about the value of scannable lists before, in Making a list? Check it (at least) twice!)

3. FAQs Are Not Efficient Communication

Why make people look for the question?

If you know the questions people are asking and at which point when interacting with your product, website, or company, then you can probably reassure them without asking the question out loud for them.

The important thing is making sure the information they need is available at the right time.

As an example: The question I most often ask myself as a visitor to non-Norwegian ecommerce sites, is whether they ship to Norway. Finding out usually requires digging through shipping policies or, in some cases, going through most of the checkout process until getting to a dropdown without my home country in it.

Surprisingly recently (it’s not like the technology is new), more sites have started using IP address sniffing for good. I am thrilled when a site displays a small info banner the moment I access their site, stating whether they ship to my country of residence. THIS is what I want: information before I waste my time.

The FAQ format is inefficient. It’s not the question people are looking for. The nature of FAQ headings also often leads to having five tiny articles or sections where one slightly longer writeup would have been sufficient.

Content strategist Hilary Marsh has some great examples and does a terrific job of explaining Why FAQs are not effective web content.

FAQs Won’t Just Go Away. Why?

The UK Government Digital Service wrote FAQs: why we don’t have them in 2013.

I had hoped that by now, with increased focus on usability, scannability, and search engine optimization through keyword frontloading, that new products might start avoiding the FAQ format.

Still, I keep hearing “and then we’re going to need an FAQ”. My suspicion is that:

  • “FAQ” has become shorthand for either “bite-sized information” or even “searchable documentation”.
  • Most people wouldn’t bat an eye if they clicked on “FAQ” and found a knowledge base without question marks in the headings. As a writer, I may obsess over genres, but I know that most readers don’t. Neither do the managers that tend to bring up the requirement.

As for search engine optimization, the pendulum swings. Many search engine optimizers are adding more questions to their content in attempts to get into Google’s featured snippets, the “answer box” displayed above all the other search results.

The sad thing here is that Google’s logic for picking answers seems primarily focused on the question and its exact wording. The quality or accuracy of the answer appear secondary, demonstrating again that the question really isn’t what the user is looking for. The logic needs to become a lot more sophisticated, and I assume it will.

How To Kill An FAQ

Over the years, I have v e r y slowly worked my way up from growling “NO!” and sharing that link from the moment someone mentions “and we need an FAQ”.

Now, I’ll let at least a few seconds pass! I might not even speak the words “FAQs must die”.

On a good day, the cool, calm, and collected answer is: “Of course we need to make sure we are answering people’s questions.” Or even, if you know the scope is significant, “Sure, we’ll need some sort of knowledge base”. And then “What are the questions people are asking, and when? Do we know, or do we need to start finding out?”

You should be the one looking for questions, not your reader.

And if you can answer before they even think to ask, the FAQ is well and truly dead.


Editing T-shirts Technical Communications

Link Roundup: APIs and Fine Manuals

Still wrestling with my next post on error messages. Meanwhile, I’m sharing some excellent links on technical communications I’ve happened upon lately.