Before you go, join the Friendly Docs Society!

I don't email often, but when I do, it's good stuff (if I do say so myself).

I will never send you spam. Gross. Unsubscribe at any time.

Powered By ConvertKit

6 Documentation Myths That Are Hurting Your Business

6 Documentation Myths.png

Both the internet and bookstore are full to the brim with information about how to set up, run, manage, and get value from development teams. But for all that information, there's comparatively little about how to do the same for documentation. Docs seem to be a dark spot in the software development universe ‒ it can be hard to navigate. How do you know you're doing what's right? How do you know you're avoiding the pitfalls? And does any of it matter anyway? After all, docs don't have a profound effect on your business—right?

Let's dispel 6 documentation myths that might be hurting your business.

Myth: My product is so well-designed it doesn't need docs

With the rise of strong UX and UI techniques, this myth has become pervasive. And it's easy to see why: as websites and apps embrace simpler designs—and as users develop the intuition to go along with them—it's easy to imagine your product is above question. 

But this is a short-sighed approach when it comes to something as crucial and your users' end-to-end experience. After all, no matter how well-designed your product, it will never be intuitive to all users: there are users who are newer to technology, newer to our cultural conceptions of intuitive design, and so on. Having documentation provides a safety tether that catches users before they fall and helps keep them soaring through your software.

Additionally, end user documentation is hardly the only kind of docs. If you expect other systems to hook into yours, you need API docs to help developers learn where and how to hook in and use your features. If you make enterprise-level software, you'll need often need installation and deployment instructions for the backend users responsible to set up the system. Even if your organization has employees for this purpose, those people aren’t born with the knowledge needed to install the system; throw them a bone and write it down.

Myth: "Documentation" means "technical manual"

The insidious thing about this myth is that there is an element of truth to it: documentation can be a technical manual. But technical manuals are far from the only kind of documentation, and they're rarely the best option for your audience.

In addition to technical manuals, there are quick start guides, quick reference guides, searchable online help, API documentation, installation guides, and many others. If you have a simple system with a well-designed UI that only performs a handful of tasks, your documentation might consist of robust UI text, well-written tooltips, and a strong initial tutorial.

The main thing when deciding the best kind of documentation for your system is to consider who your audience is, what they want from the system, and what questions and pitfalls they might encounter. As mentioned in the point above, you can design your system around some of these, but it's impossible to design around all of them. Having even cursory documentation helps save your customers time, money, and frustration. It saves your support line for actual problems, helping you get the most bang for your support buck.

Myth: Only a tech writer can create documentation

You could call this the "One weird trick (Tech Writers hate this!)" of documentation... Except that it's neither weird nor hated by tech writers. Although technical writers add value to your software development team, we’re not the only ones capable of creating documentation. In some cases, we’re not even the ideal person for the job. 

Technical writers are good at:

  • Writing well

  • Improving existing writing

  • Architecting documentation

  • Figuring out systems they're not familiar with

  • Explaining systems to people who also have no experience

  • Determining the appropriate level of communication for a given user community

  • Many other tasks

Technical writers are not good at:

  • Knowing the system as deeply and intimately as your SMEs

This isn't to say that tech writers can't get to know the system as well as an SME. Indeed, through their work, they're bound to attain SME status on the portion of the system they documented. But they attain this depth of knowledge through careful study and by speaking with the SMEs. Because of this, it can be faster and more effective to have SMEs (developers, business analysts, product owners, and so on) write preliminary documents. Once done, they can pass these drafts to the tech writer to convert into something appropriate for the user community.

Because the drafts will pass through a tech writer, they don't need to be well-developed. An outline of functionality is a good start, especially if it includes considerations the users will need or information about system “quirks.” If you have a tech writer on your team, work with them on the kind of information they want SMEs to submit and how. (Or get started with my free system outline worksheet!)

Myth: Documentation doesn't work in Agile

I've written about this many times before but I'll reiterate. Documentation not only is possible in Agile, it works better. In Agile, documentation works exactly like development: the technical writer gets the information they need from the user stories, creates their deliverables, asks questions as needed during the sprint while the information is fresh in the team's mind, sends the docs out for QA, and produces and finalizes them at the same time as the devs finalize the code.

It may come as a surprise, but a waterfall documentation style is actually much more difficult and a much greater waste of resources than Agile. In waterfall documentation, the technical writer doesn't have access to the same resources that development does: no requirements, no stories. Because of this, they must wait to begin writing until there's a finished system, wasting time. Since they have no context about how the functionality works or dovetails together, they ask a lot of questions. This is typically right in the middle of QA or release preparations when the team’s bandwidth is very low. As a result, writers are forced to cobble together documentation that's less effective than if they had a good understanding of the system to begin with. Because the system is in testing as the writers write, they also spend significant time combing through the system for changes, and often miss them. They race to prep the documentation for release, compressing their own review time. Since the team continues to be busy throughout the software release prep, the team also isn't available to review the docs thoroughly. The final result is documentation that is shoddily written, shoddily reviewed, and not robust enough to provide high-quality help to the user.

Compared with incorporating documentation into the Agile team, this waterfall style documentation development is a huge waste of the tech writers' time (especially during the "hurry up and wait" phase before there's a system to interact with) and the resources that time represents. Agile is a much better documentation approach that leverages the entire team and helps refocus documentation as the critical deliverable that it is.

Myth: The docs don't need QA

Although some documentation systems don't require the QA department specifically to create and run test cases, the documentation still needs QA; i.e., a documentation review.

If you have an online help system, there should be a QA step for the system itself. But whether you have an online system or not, the most important concern during docs review is whether the information is clear, correct, and concise. The QA team can certainly perform this task, but it's better if SMEs perform the task. I have an entire post about how to review docs, and another about how to help the team understand docs reviews. In short: the team needs to read the documentation carefully, confirm whether it describes the system accurately, assess whether the content will be clear and understandable to its intended audience, and verify that it doesn't ramble or become confusing.

The basic idea is that documentation—just like code—is created by fallible human beings. Carefully QAing the docs helps ensure the docs are the best and most helpful they can be when they go out the door, and that your team is putting their best foot forward system-wide.

Myth: The docs don't really matter in the long run

This is probably the "alpha myth” from which the others spring. After all, if the docs don't matter to your business, it doesn't matter what type of docs you have, who writes them, whether they're integrated into Agile development, whether they’re QAed, or whether they exist at all. If the docs don't matter to your business, you can move forward without worrying that you're missing an opportunity to give the most to your customers.

But this myth couldn't be more wrong. Ignore the docs at your peril, because they affect two of the most important parts of your business: your bottom line, and your brand.

You're creating a product you think your customers will love (or at least one you think they'll pay for). Perhaps they do pay for it; perhaps they do love it. But if they run into problems they can’t resolve, they'll stop being happy—and stop paying—fast. Consider the last time you encountered an insurmountable problem with a product. It ruined your experience with that product, didn't it? The tire center that sold you 80,000-mile tires that only lasted 10,000 miles, then refused to issue a refund (but did offer to sell you new tires). Or a piece of software that's supposed to help your business succeed, but the moment you want to do something a little complex, you can't figure out how. If there's no help, you're going to abandon that product in favor of one that helps you get the job done.

But, you say, we have a support email/phone/chat/Skype/in-person visit/bespoke carrier pigeon service! If our users have problems, they can reach out to someone and get an answer. And that might work while your business is small and you don't have a lot of customers. But as your business grows, the support need grows with it. Eventually, you'll need tens or hundreds of person hours each day or week to keep up with the demand. You can keep hiring agents to provide instant service to your customers or you can use a phone tree that will help direct customers to wait for the best agent to solve their problem. But soon you’ll run into the issue of customers abandoning calls, feeling angry they're not getting the service they're used to, or just being too tired or too busy for the wait. Once again, trust and interest in your product plummets. 

But if you have a comprehensive and easy to use documentation, the need to lean on traditional support lessens. Documentation won’t remove the need for live help—it doesn’t solve errors in code or design—but as your customers become more and more comfortable with the docs, they search for solutions rather than wait for an agent. This lets customers who don’t need an agent quickly solve their own problems, reducing the wait for customers who do need to speak with an agent. The benefit is that it isn't significantly more expensive to help 1000 people than it is to help 100. Additionally, since a larger proportion of issues reported to support are real issues, you get more out of every support dollar.

Although it can seem like an uphill climb when you first look at implementing documentation, the benefits to your business are enormous in terms of both cost savings and in terms of how your customers and potential customers view your brand.


Don’t forget to grab your copy of the System Functionality Outline worksheet! Whether you’re helping a tech writer or bootstrapping your own docs, it can be hard to know what information your users need. What are the most important topics? What information do users need?

This worksheet walks you through identifying and describing the most important functionality for your users. Use this outline to start building better docs that meet your users’ needs.

Join the Friendly Docs Society!

I don't email often, but when I do, it's good stuff (if I do say so myself).

I will never send you spam. Gross. Unsubscribe at any time.

Powered By ConvertKit