Elements Of Writing Good Documentation

For code, open source software, tools, and more

Have you ever heard the phrase, “Read The Finely-written Manual?” The manual, being the ultimate source of truth and value for that tool or framework you’re learning; at least, so it should. Like many of you developers, members of TechMasters have some pain points and words of wisdom to share regarding how documentation (or “docs”) should be written or read, which I have summarized here. Like software, documentation should be carefully planned, organized, and optimized for easy consumption.

Element #1: Be Inviting

Like a gentle, yet adventurous path laid before you, getting started should be as easy as taking a breath, or walking on solid ground. Though it should go without saying, the docs for your tool should be prominently accessible from the site, repository, or interface where your program resides.

In repositories, there’s the README; on a website, it should be one of the first three navigation links; in command-line interfaces, create a man page. If you have the benefit of using a website or something markdown-like, then users can have the added benefit of being delighted at first sight.

Introductions

In many cases, your users will first get acquainted with your software by scanning the README. Having a logo and slogan is fancy, but what matters is the introductory paragraph. You may even give it an Introduction heading. Illustrate the context of your software while keeping in mind:

• Who will be using it?
• Why would they want to use it?
• What value can it bring?
• How will it fit into their current work environment?
• Do not assume prior knowledge.
• Keep it very, very short. If I need to scroll, it’s probably too long.

#2: Be Succinct Whenever Possible

To play it safe, assume the worst situation possible for your readers: they’re impatient, under pressure by time, are inexperienced, or are too experienced to be bothered with detailed explanations and fluff. Your docs can have multiple paths, but there should at least be one obvious and painless path.

Whether it is a README or a Quick Start, try to achieve the #1 thing your readers are looking for: a guide that gets them going from nothing to something with a rudimentary understanding in under an hour (though under 10 minutes would feel especially rewarding — strive for even less). Also, do not call your guide something like “10 Minute Quick Start” because that may be a promise you cannot keep. The last thing your docs should be is long and disappointing.

Lastly, try not to patronize your readers with words such as: “simply,” “just add…,” or “easy.” Experienced developers would roll their eyes, and frustrated users would feel irritated. Documentation should inherently be “simple” and “easy,” so there’s no need to announce it in every other sentence.

#3: Add Optional, Useful Examples

Optional, meaning you don’t need to have an example next to every sentence unless necessary. Useful, as in do not use foo() or var bar = baz; they’re meaningless and do not help users name their variables!

For front end tools, a single robust example should be placed right after your introduction — like an inviting, low-hanging fruit. If the example can be rendered, definitely embed a self-running application such as codepen or jsfiddle.

For APIs, docs and examples are clearest when structured like the API they represent: with a header for every resource path and method combination. Adding interactive examples for your API may be more trouble than they’re worth.

I’m less enthused about interactivity as well; I care much more about having a plethora of example outputs given specific request params. I’ve also run into a system where the “interactive” version of the docs didn’t run on the latest version of the API, and so was often out of date. — Brian Irish

#4: Write Self-Documented Code

Some users will look at your codebase as a source of absolute truth and understanding, especially if you’re maintaining an open source tool or framework. Though it is debatable how much should be commented, making the code itself more readable is your highest priority; only when you cannot make a complex operation readable should you add comments.

For internal or private code, self-documented code is your best option to save time and resources over not writing real documentation. If you expect to on-board new developers quickly, they will need to inherit a digestible codebase.

I’d say if you aren’t going to document in a readable format (markdown, html, etc) at least comment your exposed methods in your codebase so when others read through it is digestible. — Nijiko

#5: Maintain Your Docs

Your docs are a part of your software. As such, they need to be maintained and updated (and sometimes, versioned) with every release. They are part of your development scope; so if you plan on including docs, make time and effort for them.

Build around your community

Whether your tool or framework is paid or free, engage with your users. Use as many avenues as you can budget: email support, social media, local meetups, blogs, conferences, and videos. When you receive common questions, do any of the following:

1. Augment your documentation to clarify missed points.
2. Answer common questions in an FAQ.
3. Create in-depth examples covering common scenarios.
4. Record video tutorials in long and short formats to complement interactive examples. Having a separate repository with downloadable examples is helpful for users to engage while following your video.
5. Blog about common user stories that apply to your project.

Templates

There are dozens of docs templates on the web, but they’re only as useful as their content. Here are some picks to get you started:

• https://pages.github.com/
• https://www.algolia.com/
• https://readthedocs.org/
• https://www.gitbook.com/

Great Documentation Examples

Simple things should be simple, complex things should be possible. — Alan Kay

fancyapps/fancyBox

Fancybox’s README features all the right elements: an introduction that doesn’t assume lots of prior knowledge, short and descriptive code snippets for on-boarding, and a succinct introduction to its many advanced features that a user can view in greater detail in the full docs.

Introduction - Vue.js

A hallmark of excellence, a lot of care went into VueJS’s documentation. featuring an optimised sidebar navigation that works well when read linearly or if the user decides to jump to a specific, clearly-defined topic. None of the pages are too long — I’ve seen other docs that have opted in to a super-long single page design, and that leads to framerate drops! Every heading has a succinct description that brings developers of all skill levels right into the useful parts of the framework. The Algolia-powered search bar is also a big help.

Documentation for Visual Studio Code

A lot of nice things can be said about Visual Studio Code, but their introductory docs and changelogs are delightful. All nuanced UI updates have a brief description and are accompanied by animated GIFs. Throughout most pages, there are handy links that can help users discover useful features they may have not sought otherwise. All in all, the documentation can help users master VSCode’s features in a very short time.

15 Ways to Write Self-documenting JavaScript

There is optimised code, and then there is human-readable code. Whichever side of the fence you’re on, you should always consider naming your variables and methods in a consistent and understandable way in case your code ever gets handed off to another developer. Though this article offers great advice for JavaScript, a lot of it can be transferred to other programming languages.

“It Depends”

Almost like art, where inspiration begets its piece, the software begets its documentation. Everyone has different expectations and needs beyond the cases I covered. It’s always tough to please everyone, so all you can do is be critical, accept feedback, follow good elements along with your instincts, and try making documentation that you would love to read.

If you have some documentation you would like me to inspect, leave a comment or join the conversation at TechMasters.chat! We’d be happy to lend our expertise.

#TechMasters