Modern Technical Writing: An Introduction to Software Documentation

by Andrew Etter

Don't write often, anyway. Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn't comprise more than 10% of your time.

They mean they spent the entire day engaged in the writing process. And a big part of that process is installing, configuring, and testing software. In other words, learning.

Because version control systems are designed for software development, each and every one of them is overkill for the typical documentation workflow. For example, you'll probably never need git reflog. So why worry about which system you use, when they can all do the job? Because when you select Perforce, Subversion, or CVS, you are basically confessing to potential contributors that you can't be bothered to use modern tools.

If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. The approach has some real appeal: Documentation and code branches stay in sync. Developers are more likely to contribute if they don't have to clone a separate repository. Of course, this approach also has some cons: If a repository is large (e.g. 2 GB), checking out the entire repository just to access the 40 KB ./docs directory can dramatically slow down documentation builds. Onerous commit hooks and pull request submission policies, designed to keep a code base stable, can make even simple documentation changes a chore.

Wherever you store your documentation, place a file named README.md in the root of the repository (or in ./docs). This Markdown file should include: A quick summary of the product being documented Instructions on how to build the documentation locally Instructions on how to contribute

If you aren't keeping an eye on documentation metrics, you're making a huge mistake. User research is wonderful, but knowing exactly which pages are most popular, your site's bounce rate, and common behavioral flows are all invaluable.

Metrics rarely serve as an obvious pointer to the correct course of action. Rather, they serve as a valuable check against your thoughts and intuition. If you create what you think is an amazing bit of documentation, and sure enough, it's one of the most popular pages on the site, perfect! If it's not very popular, maybe no one can find it, or maybe it's not as useful as you thought. Deeper investigation might reveal a major flaw, a minor tweak, or a reasonable explanation that requires no change at all.

Writing content for translation means meticulous review of new content, because any inaccuracy has to go through costly revisions. It means rarely refactoring old content because of the sheer expense involved in translating it into eight different languages again7. It means delaying software releases because it's Carnival in Brazil8 and the Portuguese translations won't be ready for another week.