Six characteristics of good docs

Daryl White
Six characteristics of good docs

Credits:

Good docs have (at least) six key characteristics:

Findable

For documentation to be worth the time spent creating it, the user needs to be able to get to those docs when a problem or curiosity creates a need for information. The best docs do nobody any good if they can’t put their hands or eyes on them when they need them.

The most common way to make docs findable in the modern world is to host them on the web and let Google and other search engines crawl them so those docs can be included in search results. This method may or may not be desirable. For one, search engine optimization (SEO) is a methodology all to itself that not everyone can devote the necessary attention and resources to execute well. SEO changes at the whims of the search engine algorithms that do the crawling.

For others, there may be many reasons to not include documentation on a public web. Some concerns may include privacy, security, competitive intelligence concerns, hosting costs, and others.

Other options for making documents findable are

  • include them as part of the app or software, often accessed on a desktop computer by pressing F1 or on a mobile device by tapping a question mark
  • print a manual and include it in the box with the provided goods, such as is often the case with furniture
  • provide a PDF of the manual that users can download from a secure link

Whatever the method, make sure that your users can find the content to consume it when the time comes.

Accessible

There are two kinds of accessibility to be concerned about for docs, and both are important:

  1. Legal accessibility
  2. Language accessibility

Many countries have laws that require accessibility that may or may not apply to your situation. For example, Section 508 of the U.S. Rehabilitation Act and Americans with Disabilities Act are two of several laws that may speak to requirements that apply to your documentation.

Docs that address this kind of accessibility seek to make documentation available to everyone, regardless of ability or disability.

  • What do your docs sound like when read by a screen reader?
  • Do you rely on color to communicate meaning? What do your docs look like to someone who has deuteranomaly, protanomaly, tritanomaly, or other types of color blindness?
  • If you use audio and video for documentation, do you provide transcripts and captions for those who are blind, have hearing loss, or both?

Language Accessibility

Another consideration for good docs, the language used for the docs has significant impact on its availability to an end consumer. After all, if your docs use language that does not communicate to the user consuming them, then they have failed.

  • Is the doc available in the user’s language or dialect, including offering translation, localization (l10n), and internationalization (i18n) where needed?
  • Does the doc define all jargon or acronyms used so that it is approachable by someone new to the industry, concept, device, or software?
  • Does the doc’s readability include or exclude the audience you are writing for?

Scannable

One common thread among tech writers and other writers for the web is the axiom that web user do not read, they scan. This means rather than reading through the entire contents of a page or article, users instead hop around with their eyes until they land on an information scent that piques their interest. Once they find the scent, the user pauses and reads the section.

Rather than fight against this impulse of the modern reader, good docs anticipate it and facilitate this practice.

Good docs make use of appropriate headings, lists, and formatting to make the writing scannable by the modern user. (Have you noticed that I’ve done some of that in this very article?)

Searchable

The ubiquity of Google, Bing, Yahoo, DuckDuckGo, and their non-USA counterparts means that many readers are used to typing in a string of characters or natural-language question into a box on the page and then seeing a list of relevant matches that might be just what they are looking for. The modern world is inundated with data. And the only way to make it through to find the proverbial “needle in the haystack” is by relying on the powers of search.

Good docs make use of this, too.

Most modern programs for delivering docs that are not on paper have some facility for search. This might be the mere, humble CTRL + F keyboard combination in Microsoft Word, or it might be as complex as a lengthy SQL statement.

Your search might only allow for basic word searches. Or, your search might take advantage of efforts at machine learning that allow for a rich natural-language processing to determine a user’s need.

Whatever your method, search is important. Search may allow a user to find your docs in the first place through a search engine. Or, even better, search may drop your user right into the very page that gives the exact procedure they need to accomplish the task at hand.

In today’s world, no one wants to thumb or scroll through a 600-page manual. They search instead.

Timely

Good docs are timely.

This means that they provide the right information that the user needs at this moment. No more, no less.

Good docs allow the user to communicate where they are stuck and then provide just enough information to get them back on their way. The docs understand what it is that brought the user to this frustrating juncture, they know where the user needs to go next, and they know how to get the user there.

To do this, the docs (well, really, the tech writer), must have a good understanding of the user’s journey in the product or software. The docs need to communicate what it currently takes, right now, in what is today, to get the user to the next step.

And then the docs let the user go. After all, if they get stuck, they can always come back.

Complete

Last, good docs are complete. They have all of the information a user might need to get from the beginning to the end of their use of the product, tool, or software.

No steps are skipped. No configuration options are left unexplained. No optional add-ons are missing. No buttons are left unexplained.

If a user has a question, the docs answer it.

Conclusion

There you have it. Six characteristics of good docs.

  1. Findable
  2. Accessible
  3. Scannable
  4. Searchable
  5. Timely
  6. Complete

What characteristics would you add that make documentation good?