Improve your documentation by limiting its scope

It's tempting to think that good documentation is complete documentation, but any experienced tech writer knows that there's no such thing as exhaustive documentation. There's a scope to all documentation, and it's not a shortcoming that your manual for a text editor doesn't also teach touch typing, nor how to program a text editor from scratch. Like any relationship, the trick to complete documentation is communication. You can tell your reader generally what they're expected to already know, and what you intend to teach them. If a reader's expectations don't match your promise, then it's better for everyone to identify that mismatch early. There are several ways to communicate the scope of documentation to your reader, and by doing that you can even help your reader find the information they're actually looking for.

Set expectations early

Your technical documentation exists for a specific purpose. It might describe a single application, it might teach broad concepts that apply to many use cases, or it might compare and contrast different solutions to a single problem. Whatever purpose your documentation serves often seems obvious to its author, but readers can't be expected to anticipate why a document exists. One reader might expect documentation to serve as a step-by-stop introduction to a product, while another might just use it as a reference when they run into problems while exploring a product on their own.

Tell your reader what purpose your documentation is meant to serve. You don't have to "sell" the documentation to your reader, but do provide an objective statement of intent. If you believe your documentation must be read from cover to cover for the sake of security, then tell that to your reader. If you believe your documentation is a quickstart guide, tell your reader. If you believe your documentation is a perfunctory listing of every function in a product, let your reader know that.

Setting expectations helps users understand where to begin, and it helps advanced users skip over the stuff they already know.

The art of helpful referrals

Even in the most complete documentation, there are some concepts you just can't tackle. When explaining a potentially advanced concept is out of scope for what you're writing, consider referring your reader to a source where they can find out more. While this is a seemingly simple trick, it's actually difficult to get right, and in its worst form results in dozens of links to Wikipedia articles for topics your reader could have found on their own. There's a balance to be struck between helpful referrals and stating the obvious.

The secret is to prioritize the sources you're willing to refer your reader to. Here are my rules, in order of preference:

1. A document I've written
2. A document on the same site or intranet as my document
3. A document on an authoritative site for the topic being discussed (for example, linking to python.org when discussing Python)

I usually forego referring readers to well known websites (they can find that on their own) or to websites I don't own or control (it may not be around tomorrow.)

The art of helpful deferral

Not all information can be conveyed or learned at once. Sometimes you might find yourself describing something that requires special knowledge you can't explain until later in the documentation. In that case, consider these two ways of mitigating the problem:

Review your document's outline to determine whether you're delivering everything in the correct order. It could be that some information you thought would be best later in the documentation deserves to come earlier.

If you're happy with the way you're explaining things, then rely on communication. In your documentation, acknowledge the gaps in your reader's current knowledge, and assure your reader that you're going to explain some details at a more appropriate time. For now, they can take it on faith and still understand the process you're describing.

When something is out of scope

Finally, there are some topics that are just out of scope for your document. When there are topics out of scope for your document, but you know that it's specialized knowledge, tell your reader that they don't need to fully understand what your document is discussing.

You can use the concept of a "black box." Input is received from an unknown source, in an unknown condition. As long as the outputs line up with the appropriate inputs, the technology works. Your reader doesn't need to understand everything to understand cause and effect. Provide your reader with referrals, as appropriate, so they can learn more if they want to.

And with that, we've come full circle.

Specific documentation for optimized learning

It often seems appropriate to try to explain everything about a topic. That may well form a definitive volume about a technology, but that doesn't mean it'll be useful in practice. Identify for yourself what you're trying to convey to your reader, set expectations for your target audience, and keep the scope of your document in mind. Documentation that's specific to its topic is very often optimized documentation that's easy to maintain, and helpful to readers.