Omission is an unacknowledged art.
Anything well done owes its success partly to apt decisions about what to leave out, whether the creation is software, or a work of popular culture, or something else. And disordered clutter is often found in less successful endeavors.
This is true of software documentation as much as anything. Removing clutter leaves the important parts easier to find and understand. It makes the job of organizing docs easier, because there's never a good place to put something when it doesn't belong. And it makes the docs easier to maintain, for the reasons above and because there's less text to update later.
Here are some strategies for leaving things out.
Write articles that are about one thing. For example, explain how to do a single task, and only offer one way to do it, even if there are multiple ways. Or use a conceptual article to explain one concept or one group of closely related body of concepts, if understanding depends on knowing all of them. Using a singular focus simplifies the author's task of deciding what should be included. It simplifies the readers task of deciding whether the article contains what the reader is looking for.
Omit information that doesn't fit the type of article you're writing. Don't sandwich concepts into the middle of a how-to article. Instead, explain concepts in an article of their own, and link to it whenever necessary. (Conceptual articles help the user understand a system, whereas how-to articles describe specific steps to accomplish a task by using the system.)
Never tell readers something they already know.
Never tell readers what they don't need to know. This includes details about implementation and design of your system, if the majority of your users wouldn't need to know what's under the hood.
Use words sparingly. Leave out words and phrases that don't convey useful meaning. User fewer, shorter words to say what you need to say.
Be even more sparing with ideas. Go back over a first draft and look for places where ideas can be simplified; first drafts are often convoluted or repetitive.
Write simple sentences. A subject + action construction is always best. Follow the adage “One idea, one sentence.” Instead of tacking dependent clauses on the beginning or end of a sentence, remove them. They can either be discarded or they can be another sentence.
Knowing what to cut requires some thought about who your reader is, what they already know, and what they want to accomplish when they read the documentation. For example, API reference docs are read almost entirely by the developers, but your product overview will be scrutinized by a variety of decision makers who decide whether to adopt the product and how. Keep the audience in mind every time you update an article.
No posts

Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.