Modern Technical Writing: An Introduction to Software Documentation

by Andrew Etter

technical writers aim to produce content that their intended audiences will read and find useful.1 This has to be the goal, because any other goal is absurd.

Huge blocks of writing look intimidating, and excessive content waters down useful content. Identify what the audience actually needs to know, and include only that.

The goal of all this testing and research is to be mentally equipped to ask pointed, intelligent questions to business development, product development, quality assurance, customer support, and ideally, actual users.

Talking to people is an art.

A good rule of thumb is to treat everyone as busy individuals whose time is valuable, but another rule of thumb is to break this rule and be more of a jerk if an essential employee isn't giving you the information you need to do your job. Tailor your approach to the person, come prepared to meetings, batch your questions into related sets rather than bothering people every twenty minutes with individual questions, and thank everyone for their time. Your contribution to a project isn't immediately obvious, so try not to be put out if people aren't as forthcoming as you'd like. Technical writers need to be grinders, willing to slowly but surely chip away at the block of ignorance until a beautiful sculpture emerges—or something like that, anyway.

Don't get stuck in the quagmire of trying to help the helpless. I know it sounds cold and mean-spirited, because these are the readers most in need of assistance, but by catering to them, you are doing a real disservice to the other 90% of the population.

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.

Consistency is king.

Bias towards including headers, tables, lists, diagrams, and images. These additions make your writing more approachable and simpler to scan than paragraph after paragraph of prose.

Use inline styles to offset important text. Typically, technical writers use bold for user interface elements ("Click Save."); italics for emphasis ("You must save your work before shutting down."); and monospace for file paths, terminal commands, and code ("Run ./bin/script.sh.").

For the sake of clarity, try not to verbify obscure nouns.

Hosting your content on a website gives you the power to fix inaccuracies almost instantly and keep your content in sync with the latest software release.

However you decide to write and distribute your documentation, you should do it in a way that encourages others to contribute.

Strangers will do it for free, and coworkers will do it even if it isn't in their job descriptions. I've had colleagues argue this point with me, but no, people really will contribute if you just let them.

Ultimately, the job of a technical writer is to ensure the quality of the documentation. Hopefully you create a lot of it yourself5, but whether you write it or not is largely irrelevant to the end product. Quality is relevant.

Learn everything about a subject. Write down exactly what an audience needs to know and no more. Make the content beautiful, discoverable, scannable, and searchable. Consider everything a draft, and iterate relentlessly. Make contribution simple.

Even a relatively short and simple book like this one is a colossal task.