What Makes A Great Doc?

The need for good technical documentation is often undermined, but here's the thing: no one enjoys using something that they don't really understand.

No matter how incredible your features are, or how fascinating your internal codebase is, it doesn't really matter (it's worse, even) if proper documentation is absent. We need to understand that whether you're developing something for non-technical users, or bringing on someone internally to work with your existing codebase, you can't do without documentation.

Good documentation makes things easy - because it eliminates confusion by taking people through the hows of any process easily. For any great tech product, good documentation is as important as incredible features; or the code that was used to create it. And as a technical writer, there are simple ways you can ensure you create good technical documentation that really does its work.

Let's explore a few, shall we?

Use a Style Guide

Dear technical writer, why do I still need to tell you this?

A good style guide helps you set basic frameworks for how you should write, brings consistency in formatting, as well as show you things to look out for, saving your reviewer or editor from needless reviews at the end of your work.

Style guides help reduce confusion in your documentation, set grammar and sentence structure, as well as ensure you don't make mistakes in things like active vs passive voice, and tbe use of short forms or acronyms. The Google Developer Style Guide and Microsoft's Technical Writing Style Guide are examples of good documentation style guides for technical writers.

Gauge Your Audience

Whether this part is handled solely by you or by others, knowing and gauging your audience before hand is a big deal - whether you're writing for internal dev teams, developers working with a tool or an API, or non-technical users of a product.

Knowing your audience, as well as gauging their expected skill level (beginner, intermediate or expert) is a factor that should be handled both before you start outlining; as well as after you're done.

If you're writing a getting started with HTML tutorial aimed at beginner devs, you'll have a different outline than an API doc or a technical article aimed at non-technical users.

Focus on Clarity

For the love of God, let your document be clear and easy to read.

Clarity is an important part of good technical documentation. You are meant to make the lives of your target audience easier with documentation, not harder. Try not to use complex jargon in every third word in the bid to sound 'technical', and remember that at a fundamental level, you are writing to people. Write simply, write plainly, and strive to deliver your content in the easiest way possible, at every level. Both the Laravel and FastAPI docs are good examples of this point.

Practice (Test Your Stuff!)

Every good technical documentation is usually written by a technical writer who has researched and tested (to a degree) what they are writing about. You can't really share tutorials on React if you haven't personally used it - how are you sure the code works? You can't share a user guide on a product to beginners if you've not researched it and tested what it means to be a beginner with the product. Every great documentation has behind it a technical writer who has both research skills and the technical know-how for testing new software, frameworks, and other technologies.

Add Visuals

Many times as a technical writer, your documentation or article will have to involve charts, diagrams, and screenshots in order to help the reader (whether a non-technical user or a developer) to better understand the concepts you explain and/or the steps you outline in order to understand it better. If your documentation is a tutorial or how-to guide, diagrams and screenshots help the user follow through, ensuring they stay on the right path.

Make it Navigable

Great technical documentation is always easily navigable. Good technical writers know how to structure their documentation, laying out information in such a way that enables the reader to easily flow into from section to section, using things like table of contents, headings, subheadings and lists; as well as ensuring that each paragraph connects logically to the next one.

The best pieces of technical/product documentation I've read, has always been the ones that prioritized an easily navigable, logical and sequential order - one that makes it easy for me to go through it without being lost.

Think About Accessibility

Since good technical writing is a primary source of information about the product, tool, or process for most users; it is therefore important to ensure that your documentation is accessible. This means that you consider beforehand that while your content may address a particular target audience, that audience may be comprised of people with special needs or disabilities. Learn to use gender-inclusive terminologies such as 'they', make your language easy to understand (begs repeating), and don't forget to include graphics and images while adding alt texts for screen readers to describe them.

Here are some more thoughts on accessibility in technical documentation you can check out.

Review and Update

Finally, don't forget to always review your documentation and note new features that come up. Documentation can go obsolete if it is not reviewed and updated.

Imcorporate Preliminary User Feedback

Usability testing or preliminary user feedback, is another feature that determines a great technical doc. You'd be surprised that if you integrate this on time, you can easily account for documentation problems that may come up later on.

How do you conduct usability testing? Well, in Yocheved Stern's words: Choose users from your organization who do not know the product well. Have them go through the doc. Then prepare to eat humble pie.

Conclusion

As a technical writer or documentation engineer you can make your documentation stand out using these simple but important tips.

By integrating them into your documentation, you bring a new level of usefulness and ease. Good documentation ensures that product users leave with no confusions, and helps organizations easily transfer knowledge of your code base between internal dev teams.