Don't duplicate - Specifics

Modern technical writing - Andrew Etter 2016

Don't duplicate
Specifics

Along with accurate driving directions and videos of frolicking puppies, links4 are one of the most wonderful things the Internet has given us. The most popular sites on the Internet are devoted, in fact, to the sharing of links between friends and strangers. Making proper use of links lets us attain a sort of Holy Grail in technical writing: single sourcing.

The core idea here is that you should break your writing into bite-sized pieces, often called topics, none of which overlap in content. Doing so means that if things change—and things always change—you only have to update the documentation in one place. Many topics are short, whereas others are quite long. What topics should be is relatively complete in their discussion of a particular subject. Unlike books, where you can assume in chapter seven that the reader remembers chapter six, topics assume very little knowledge of other topics and include plenty of links.

Unfortunately, the nature of language and learning means that some amount of duplication is always going to occur. But for the most part, linking liberally, arranging topics in a sensible way, and trying to adhere to a single source model is a good idea. reStructuredText and AsciiDoc even allow you to embed files within other files, which further aids reusability.

The worst duplication sin of all is to store similar copies of the same documentation in version control. The root cause here is typically the desire to have one version for coworkers and another for customers, and it inevitably leads to a maintenance nightmare. Instead of multiple copies, the better approach is to use a feature sometimes called "conditional text." Conditional text lets you selectively include or exclude files (or portions of files) in the final output. AsciiDoc supports conditional text under the name "conditional inclusion macros." reStructuredText supports it through Sphinx with the .. only:: directive. Unfortunately, this feature is not present in Markdown. Attempts to add it can be charitably described as "hacky," so if you rely on conditional text, you might want to select another language.