Documentation for developers

Because of some organizational changes at my job, rumor has it that developers are going to be asked to contribute to writing technical documentation. Some developers on my scrum team were a little, err, concerned about that, so I wrote up some notes (and compiled some links) about our tools, conventions, and so on. I also included a philosophy section that is not specific to our product or company. I feel like I've written "tech writing basics" several times over my career; here's one more collection of quickly-compiled notes (far from complete).

--

I don't have time to develop a course in technical writing, but here are some thoughts as they occur to me.

Document the contract, not the implementation. You're deeply immersed in the implementation and might be tempted to pull content from the design spec. Instead, pull it from the functional spec. Think of the implementation the way you think of the private classes that probably make up most of it: that's for you (and you're free to change it), not for users to depend on. You expose interfaces in the code to protect the implementation; think of the doc as one of those external interfaces.

An awful lot of technical documentation that has probably frustrated you talks about "what" but not "why". We do need to describe the "what", like what all the parameters are, preconditions, interactions with other parameters/functions/etc, but ideally you wouldn't stop there. Put on the user's hat and ask: why would I want to use this? What problem does this solve? Good documentation starts from things the user is trying to do and then shows how to use (probably several) functions/statements/features/settings/etc together to do it. With luck, your functional spec starts there too, so you're not starting from scratch.

There are a few main types of documentation in most doc sets:

  • Reference pages: a complete description of each individual "thing" (class, function, command, etc) in a consistent layout with minimal distractions. Use outbound links for other supporting material.

  • Task doc: how to do a specific thing, usually a sequence of numbered steps. Keep it focused; the user is going to be going down the list probably typing (or cutting/pasting) the commands in the code blocks.

  • Troubleshooting: there isn't much of this in our doc, but some of our top-level categories end with a troubleshooting section. I build these up over time based on bugs that turned out to be pilot error, feedback from support, edge cases I notice in tests, and so on. Sometimes a functional spec calls out limitations up front and I add a troubleshooting section that approaches that limitation from the other side.

  • "Guide" doc: a mix of overviews, conceptual doc, and scenarios. This doc usually covers the "golden path" and should not try to be exhaustive (that's what the reference doc is for). You'll see some older doc in (location) that mostly repeats the reference pages without adding much; don't emulate that.

(Some doc "frameworks", like DITA, slice up the world a little differently: reference, task, concept. I naturally think my division is a little more on-point for the kind of doc we're writing, but it's just one person's opinion.)

Good examples are gold. Bad examples are tedious. One person's good is another person's tedious, but asking the question is the first step: what purpose does this example serve? Examples don't need to be exhaustive like unit tests; examples illustrate, and they show clearly how to do tricky things, but you don't need the combinatoric explosion of all possible arguments and parameter values in the doc. Examples, like doc, should be as concise as possible while still accomplishing the primary purpose.

When writing examples, it's helpful to users if you can attach some meaning - instead of an ML function operating on columns c1, c2, and c3 in table t1, can you imagine a scenario where people would actually use it and mock it up instead? Particularly for long or multi-step examples, it's easier if readers can hook onto some semantic hints, even small ones. This helps with the "wait, which one was c2 again?" backtracking that happens when reading subsequent explanation or steps. Your examples might not be completely realistic, but try for some "realism flavor".