To Document, To Write

When I am asked to define my role, I start with “Technical Writers write Technical Documentation”. But to be honest, the word in the middle is incorrect: there’s a difference between writing and documenting.

For example:

• We document API methods and parameters, filling pages with code, syntax, and expected data formats and types. Facts.
• We write technical guides, making difficult concepts easily understood, help users follow best practices, enlighten.

The difference is therefore pretty straightforward.

To Document

API documentation requires as little wording (i.e., writing) as possible. It is thorough, precise, a source of truth. Mistakes are intolerable.

The pages of good API documentation should contain mostly code and one-word descriptions like “boolean” or “optional”. The key ingredient is useful: they should be immediately useful and not get anyone to think. Tell not show, and definitely not entertain. They should get people up and running, fast.

It is different for guides.

To Write

It is different for guides.

Time slows down in the guides. For one, they require more words, more writing. They verbally walk people through concepts.

Guides make arguments, describe benefits, carefully discuss costs and benefits, alert readers to dangers, and make recommendations, encourage must-dos, and clarify what not to do. And no code allowed.

The experience is transformative. Users becomes readers. The reader goes from impatient hacker to informed coder to master developer. Better coding. Better implementation. Less errors. More advanced features.

Still more about writing

The benefit of well-written guides? The API provider is happy because its customers have more confidence. Customers are happy because the API product is kick-ass and well-implemented and easy to maintain. And the API support team is relieved that their slack channels and forum discussions are not ringing off the hook.

And the writer, well … is he or she or they happy?

Technical writing is not writing

I come from both a technical and writing background. Technical in that I was once a developer. Writing in that I loved writing as a creative and personal extension of myself. As for my technical writing background, I documented code and wrote technical and functional specifications.

I therefore documented and wrote. The difference was clear. When my audience had time to read, I had the opportunity to write longer sentences and more content.

Now, I am writing for large numbers of developers, over 10s of thousands, all of whom I will never meet except maybe on the streets of my big city, without knowing it. With this kind of anonymity, I am forced to make a compromise. I am forced to follow the model of documenting.

This means: keeping things simple, getting straight to the point, and adding no embellishments or metaphor, just facts. To minimize words, to speak in code, not computer code, but in a coded simplified language that helps developers find and digest information easily.

Not knowing your readers means not using words that will be misunderstood, so best to use as little words as possible. To write less.

Good technical documentation should be conversational

So they say. But in fact, the conversation is always the same: this is X, X means Y, and you need to use X to do Z. And there’s only so many variations on this formula, and why vary it? If it works, do it all of the time.

On the nature of truth in guides , or using metaphors in documentation

Okay, one more point. Or, where do I put this paragraph:

Some guides use metaphors. Metaphor is, for me, clearly on the writing side of the documentation/writing divide.

Is a metaphor true? This is a good question for a technical writer to ask in deciding whether or not to use a metaphor. The best answer is yes and no. A metaphor uses a somewhat true scenario as an analogy to guide the reader through a difficult concept. The analogy is usually only half true — that is, only half of it applies. The goal, however, is to get the reader to start thinking about the idea or concept in a way that seems familiar, and to use that familiarity as a metaphorical bridge to unfamiliar territory. The hope is that when they code, they’ll know what they are doing and why.

Writing is that bridge. But I’m not sure we need that bridge anymore.