What is the magic?: Thinking about good documentation

Document quality is a big part of our conversation right now so I think it may be helpful to explain some concepts associated with good documentation and share ideas at a high level that have been really illuminating for me as a tech writer.

Of course, I don’t expect everyone to become a technical writer after reading this. But if I can demystify the job and share the values that guide me when I’m working through content, then everyone can appreciate the characteristics of stellar documentation when they see it and think more clearly about how we achieve it.

Some quick philosophy

Technical doc principles often overlap with programming principles, and there are plenty of them. These mostly advocate for simplicity and clarity. But the highest principle every writer starts with is to always consider your audience.

Know your user by asking:

• What’s their role?
• What is their level of expertise?
• How are they using the doc?
• What is the route that has brought them to the doc?
• What do they expect to find in the doc, and how do they expect to find it?

The best documentation knows and serves its audience best.

An audience of engineers

We all have our favorite adjectives for engineers. A good characteristic for a writer to understand is that engineers are fast. And an eye-opening concept for me has been that engineers aren’t just fast thinkers. 10X engineers are very fast users:

• They know and use all the hotkeys and macros for their tools,
• They know all the conventions and shortcuts in the spaces where they operate,
• They skim for code blocks and numbered steps to solution by trial and error, and
• They don’t hesitate to Ctr+F your whole document before reading any of it.

These users are information foraging, so style and formatting choices for them prioritize discoverability and skimmability. Wiki pages and API docs are formatted to match conventions from the internet and from open-source examples because engineers know these formats intuitively and can consume them quickly.

For more, see What is the magic?: Features of good docs (part 2)