Tech Writing Best Practices
I’ve been combing through my old projects from my last gig, seeing which tibits of internal documentation I could clean up and share on my site for prospective employers and fellow tech writers alike.
This piece is short, but sort of an essential manifesto I still use to guide the creation of content in my own work. It’s borrowed from the work of the always-illuminating Tom Johnson and a presentation he gave on User-Centered Design. The book referenced in Tom’s slides is absolutely worth checking out on your own.
Universal Principles of Design isn’t just for UX experts or traditional design roles. As documentarians, we often forget that we don’t simply translate concepts into output for end users, but rather we have the power to design and dictate the flow of information for our audiences. We’re designers in the purset sense.
Industry-leading technical documentation is:
Readable
Sentences should be simple, clear, and easy-to-understand, especially as the concepts get more complex. In fact, the more complex the material, the simpler the sentences need to be.
Focused
Focus the users’ attention on what matters by reducing extraneous information. Eliminate content that is merely “noise” as opposed to meaningful information.
Assistive
Provide getting started tutorials and quick reference guides to reduce the burden of complexity and encourage first steps in a system.
Targeted
Create composite descriptions of users based on real research to guide decision-making about design. Three primary personas and four secondary personas are usually sufficient. When you write documentation, personas help you remember that you’re not the user.
Iterative
When writing docs, recognize the iterative element behind writing documentation is not dissimilar from product code iteration. Publishing version one shouldn’t be considered done — just the first iteration of the content.
Modular
Break up content into independent topics that can be viewed, understood, and updated independent of the whole. A topic or chunk should not be so interconnected with the whole that it cannot stand on its own.
Hierarchical
A hierarchical outline of the content (with parent and child items organized in trees) helps users both understand and visualize complex information.
Layered
Layer information so that you don’t present everything to the user at once. Make some information available only at secondary or tertiary levels of navigation.
Navigable
Provide navigational sign posts such as breadcrumbs or other workflow maps to help orient users. Don’t assume that the user navigated to the current page following the path you intended.
