Write in modules

As the saying goes, every journey begins with a single step. In technical writing, this concept is especially meaningful, because when you write about a process, there are often lots of sub-processes involved. You don't compile code without installing a compiler first, you don't open a port in a firewall until you've confirmed you're running a firewall at all, and so on.

The most effective way to write technical documentation is in modules, with each sub-process defined in its own unit, and then with each unit strung together to form the whole process. Here are three reasons you should keep your documentation modular.

1. Keep your reader's attention

Modular documentation produces "bite sized" tasks that look manageable to a new user. You can write a document that covers all 99 steps required to install and run a web server, or you can break the process into small tasks.

Most human brains are only willing to stay focused on something it doesn't understand for so long. After reading about a complex task with no obvious results, most readers unconsciously decide that there's no hope of understanding it. Small, clearly-defined tasks are easy for even someone unfamiliar with the process to comprehend.

2. Boost your reader's confidence

All technical documentation, whether the writer is aware of it or not, must "sell" itself to its reader. The average user has lots of options when faced with a technical document, and we've all been betrayed by bad documentation before. One user might choose to ignore the documentation entirely, another might choose to search the Internet for a video instead, or for something that looks more reliable, or for a document that other people say made the process easy to understand. If you want readers to turn to your technical documentation, you have to demonstrate that your solution won't lead them astray.

One way to instill confidence in your reader early is to provide a simple task they can perform toward their ultimate goal. This task must be short, successful, and verifiable. As a bonus, you might even provide troubleshooting steps for the times when something does go wrong.

Most readers won't sit through several pages just for you to demonstrate that you know what you're talking about. Make it quick, provide your reader with context for why they're doing it, and justly earn their trust.

3. Maximize the return on your effort

The more you write, the more you learn that there are many tasks you write essentially into every document. You might write the same explanation several times over of how to install an application or code library, how to grant a specific permission in an application, or how to create a new user, or how to delete an account. The second or third time you write about a process, you've likely discovered a "module" you should write instead.

When you find a common task that appears as a component of several larger processes, extract it and make it into its own document that you can link to, or otherwise include, as a component of lots of other documents. This helps break big tasks into small tasks, which benefits your reader, but it also helps you focus on writing new content rather than writing literally the same content over and over again.

Connecting the modules

The benefit of writing modularly means you can connect all the different tasks you've covered discreetly into lots of different documents. Whether you're writing about installing a code library or how to configure the new conference room projector, there's probably a task both documents have in common. Don't write those tasks again, just include the module!

A "module" has a different definition depending on what you're writing for. For documentation on the Internet, a module is likely a distinct HTML document with a unique URL. On a wiki, a module is probably a wiki topic. For printed documentation, a module is probably a separate text file that gets imported into a desktop layout application as needed. Consider your medium and your workflow, and use the concept of modular documentation in the way it makes the most sense for you.