Home Tips for Writing Good Documentation

Tips for Writing Good Documentation

Technical documentation. I doubt it’s something any of us would list as our favorite genre, either to write or to read. But it’s one of those necessities we often curse then begrudgingly accept when we have to wade our way through it in order to solve a problem or when we have to write it in order to explain a technical product.

Good documentation is hard to write. There are a number of forms in which technical documents can take: very general or high-level overviews, step-by-step walkthroughs, or auto-generated documents, for example. Add this to the variety of users who might need your documentation – their different needs, technical expertise, learning styles – and you’ll probably find there is really no one single format that will work for everyone.

Writing for the Right Audience

With that in mind, the first thing you need to consider when writing documentation for your project is audience. An end-user will want documentation that’s primarily instructional – a How-To. While some technical concepts can be mentioned (and explained), the emphasis should be on the interface, not on the back-end. Another programmer looking at the documentation will want additional information: technical details of how program elements work, where in the code actions occur, and if applicable, how to extend the code. Writing for one audience shouldn’t preclude writing for the other, but you should consider separate documents – the user’s technical documentation and the technician’s technical documentation, so to speak.

Types of Documentation

In Jacob Kaplan-Moss guide to writing great documentation, he points to three categories for documentation: tutorials, topical guides, and reference guides.

Tutorials: Tutorials are important as they are often a first impression when someone uses a new tech tool. As we’ve written about before, there are a number of tools to help you make good tutorials. But if you’re writing one, Kaplan-Moss recommends tutorials be quick and easy – but not too easy – and demonstrate how your project “feels.” Example: the user guide for the recently release Anthologize blog-to-eBook tool. Note the screenshots that accompany each step.

Topical Guides: These are, in the words, of Kaplan-Moss, “the meat of your documentation.” While a tutorial provides an introduction to high-level concepts, topical guides are for those who want to dig deeper. Their main goal should be comprehensiveness. As Kaplan-Moss notes, books often outshine the official documentation, which is unfortunate as the latter can be kept better up-to-date. Example: Django documentation – everything you need to know about Django (and then some).

Reference Guides: Reference guides are designed for those users who understand some of the “how” found in the guides, but are looking for information. “These should be designed for those who already know how to use some API, but need to look up the exact arguments some function takes, or how a particular setting influences behavior, etc. It’s important to point out that reference material is not in any way a substitute for good tutorials and guides!” Auto-generated documentation is a start, but without additional writing, editing, organization, it’s unlikely to really answer anyone’s questions.

And just because it’s “technical writing” doesn’t mean that you should forgo poetic language, grammar and spell-check. OK, well, at least please edit for spelling and grammar.

Photo credits: Flickr user John Norton

About ReadWrite’s Editorial Process

The ReadWrite Editorial policy involves closely monitoring the tech industry for major developments, new product launches, AI breakthroughs, video game releases and other newsworthy events. Editors assign relevant stories to staff writers or freelance contributors with expertise in each particular topic area. Before publication, articles go through a rigorous round of editing for accuracy, clarity, and to ensure adherence to ReadWrite's style guidelines.

Get the biggest tech headlines of the day delivered to your inbox

    By signing up, you agree to our Terms and Privacy Policy. Unsubscribe anytime.

    Tech News

    Explore the latest in tech with our Tech News. We cut through the noise for concise, relevant updates, keeping you informed about the rapidly evolving tech landscape with curated content that separates signal from noise.

    In-Depth Tech Stories

    Explore tech impact in In-Depth Stories. Narrative data journalism offers comprehensive analyses, revealing stories behind data. Understand industry trends for a deeper perspective on tech's intricate relationships with society.

    Expert Reviews

    Empower decisions with Expert Reviews, merging industry expertise and insightful analysis. Delve into tech intricacies, get the best deals, and stay ahead with our trustworthy guide to navigating the ever-changing tech market.