Modern technical writing - Andrew Etter 2016

Basic functional documentation
Basics

Now that we have knowledge and an audience, it's finally time to write. Basic functional documentation (BFD) is exactly what it sounds like: a big... fine deal. At a minimum, product documentation should answer the following questions:

· What is this product? Why would anyone want it?

These two questions are incredibly challenging for the average technical writer, a group of people much more focused on how than what or why. I've struggled with them many times. But if you can't answer these questions, you need to go back to the research phase, because you don't understand your audience at all. The answer to this question shouldn't come from a marketing department. Instead, it should be an honest, buzzword-free appraisal of capabilities and use cases.

· How does this product fit into a broader ecosystem, if at all? Does it have any dependencies?

The answer to this question can be a single sentence, an architecture diagram, or a complex discussion of the various components necessary to create a coherent product stack. Web frameworks are perfect examples, because it's so rare to use one in isolation. They're typically paired with several complementary products, and developers need to know which ones prior to installing.

· Where can I acquire this product? If there are multiple distribution packages, which should I choose and why?

One of the nastiest things you can do to readers is convince them that your product is useful and desirable and then direct them to a download page with fourteen different files and no guidance on which are appropriate for which users. Some people can distinguish between .zip and .tar.gz, but many cannot.

· How do I install the product? What are the basic configuration options, if any?

For consumer applications, the install process should be so streamlined that this section barely needs to exist. For server applications, it's often the longest, most critical part of the documentation.

· What does a simple, start to finish operation look like?

This section can be anything from a pictorial walkthrough to a functional code sample—to be clear, not just a couple snippets—but whatever it is, it should take the user from nothing to something. It should be meaty enough to convince readers that they've learned something.

And that's it. The good news is that the principles of BFD are as applicable to vacuum cleaners as they are to databases. I created the following example for the overpriced glass cone that I use to make my morning coffee:

Manual drippers give you total control over how you brew your coffee. You can customize the temperature of the water, the rate at which you add water, and the sheer amount of water to arrive at your definition of a perfect cup. If you aren't picky and just want a cup of decent coffee in the morning, a conventional machine is a better option. This method does not produce espresso.

Because of their unique shapes, drippers often require specialized filters. You also need a gooseneck kettle in order to more precisely control the flow of water. Some electric kettles have built-in thermometers. If yours does not, you can use an instant-read thermometer. A digital scale lets you measure the amount of coffee and water you use in the brewing process, which helps with day-to-day consistency. Finally, you need a burr grinder to reduce your whole beans to a nice, uniform grind. The total cost of this setup ranges from $150 - 500.

You can buy all of these products from Amazon. A manual burr grinder will save you a lot of money compared to an electric model, at the cost of your time and muscles. Avoid cheap blade grinders, as their inexact grinds ruin good coffee. Most other components are of comparable price and quality.

Once you have everything, adjust your grinder's settings until you arrive at a grind that is coarser than espresso, but much finer than French press. Vary this setting over time until you arrive at your favorite grind, and then make note of it. You can do the same thing with your water temperature. 200 °F is a good starting point.

To brew a cup of coffee...³

In very little space, I answered each BFD question. BFD gives you a baseline level of content for which to strive, but it also has the happy side effect of keeping you focused. Because the above example documentation is for a glass cone, I only provided the level of detail required to "operate" that cone. I didn't delve into how to adjust a burr grinder or electric kettle, just that you should arrive at semi-fine coffee grounds and 200 °F water. Links to grinder and kettle documentation (if any exist) would be great additions.

Tip

Whenever possible, don't write from memory. Verify content as you write it. If the documentation involves shell commands or code snippets, copy and paste them after validating that they work.