A Guide to Writing Your First Software Documentation

As a developer, your pride and joy is your code. It’s readable, it meets DRY principles, it reflects best practices, and the end product is a great tool that solves some kind of problem for its target users. However, no matter how much work you’ve put into your code, if your software comes with no documentation, or you write documentation as an afterthought and treat it with little importance, it’s likely users will find little joy in working with it, and eventually opt for a different, more user-friendly product.

In this article, you’ll find a number of practical guiding principles to get you up and running with writing your first software documentation.

Why Documentation Is Important

In reference to your software, Mike Pope has a fitting saying that goes like this: If it isn’t documented, it doesn’t exist.

Why’s that? Well, just to take my personal experience as an example, I was browsing the Web looking for new JavaScript animation libraries to try out and I came across one with a description of its features that I really liked. However, there was no documentation, not even a Getting Started section, but just a bare-bones API page with almost no explanations or examples. Do you think I ended up using that library? Of course, I didn’t. I got so frustrated with it that I moved on to something that made more sense to me.

To the question of why good JavaScript libraries fail, Nicholos Zakas gives the following answer:

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.

Another important reason why your software docs are crucially important is that they serve as a communication tool between your present self and your future self, and also between your present self and other developers who eventually might find themselves working on your software. Even if you write readable and commented code, this doesn’t necessarily mean it will still be clear to you in six months’ time why you wrote a function, or any other piece of your code for that matter, the way you did.

Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why, and not the how, documentation serves the same purpose. — A Beginner’s Guide to Writing Documentation

Surely, you want people to use your code and also to be able eventually to update it and improve on it. These are all contributing factors to the growth of a supporting community behind your product, which is important for it to gain robustness, maturity, and success.

It’ll be mighty hard to accomplish all this if your software doesn’t have great docs to go with it.

Who Software Documentation Is For

When writing anything, make sure it’s clear in your mind who your audience is. Docs are no exception to this rule. Doing so clarifies in your head the problems your audience is likely to face, the familiarity it’s likely to have with your product or the prerequisites for using your product. This information is crucial to the way you create the content and the language you use.

There are two kinds of documentation this article is not concerned with:

1. User manuals. For instance, my sister might decide to use WordPress for publishing her own blog. She’s not a developer, but she’s heard that non-devs can get their blog up and running in no time with WordPress. Now she’ll be needing instructions on how to download and configure the software on her server, how to write, publish, and update her posts, how to add images to a post, etc. In other words, she’ll need a user manual.
2. Project documentation. This kind of documentation has more to do with the project than with the software itself, although some of its content could go in a project’s Readme file. To continue with the WordPress example, after getting lots of practice with WordPress, I might decide I’d like to add a feature to the software or fix a bug or two. In this case I’ll need to know things like changelogs, conventions and best practices, contribution policies, how to participate in team discussions relevant to the task at hand, etc.

The kind of documentation I’ve got in mind here is mainly aimed at developers who have different levels of familiarity with your software and need to use it in their projects. For instance, if I’m creating a WordPress theme, then I’ll need to know how to get started, how to include style sheets and JavaScript documents, how to communicate with the database to display posts, etc.

What to Include in Your Documentation

A popular approach is Readme Driven Development, championed by Tom Preston-Werner. It consists of writing the Readme document before you even start writing any code. This document is an introduction to your software and usually includes:

• an explanation of what your software does and what problem it solves
• an example illustrating the circumstances in which your code would normally be used
• links to the code and bugs tracker
• FAQs and ways to ask for support
• instructions on how to install your software
• license information

However, in my view, having a solid documentation that can really help developers who use your software/library should go well beyond the classical Readme file. Following Daniele Procida, I suggest you include the following items in your documentation material for a great user experience.

Tutorials

A beginner will love to find a tutorial in your software docs. Tutorials are about showing users how to complete a project using your software, so that they can quickly get a sense of what they can do with it.

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it. — Daniele Procida

How-to Guides

How-to guides help users solve a real-world task using your software. Procida compares them to recipes in the sense that they are directions you give users so that they can successfully reach a certain goal. Unlike tutorials, which are aimed at complete beginners, how-to guides assume users already possess some basic knowledge of features, tools, and of how to perform simple tasks.

Reference Guides

Reference guides are technical references of your software’s code — functions, APIs, etc. — and offer a basic description of how to use the software. For example, you’ll find an illustration of how to instantiate a specific class, how to call a particular method, and so on.

Reference guides are technical descriptions of the machinery and how to operate it. — Daniele Procida

This is the piece of documentation you’re likely to find in most projects. Developers tend to be quite good at writing it since they know all about their code and how to use it.

Explanation

Explanations are a deep dive into, or a discussion on, a particular topic you think is relevant to a higher-level understanding of your software. About explanations, Procida points out that —

This section of documentation is rarely explicitly created, and instead, snippets of explanation are scattered among other sections. Sometimes, the section exists, but has a name such as Background or Other notes and doesn’t really do justice to the function.

A topic isn’t defined by a specific task you want to achieve, like a how-to guide, or what you want the user to learn, like a tutorial. It’s not defined by a piece of the machinery, like reference material. It’s defined by what you think is a reasonable area to try to cover at one time, so the division of topics for discussion can sometimes be a little arbitrary.

Things You Need to Pay Attention To

Let’s go through some useful pointers about making your docs user-friendly and relevant.

Make Your Docs Discoverable

It’s a good idea to put some work into making your software documentation easy to find. You could use some SEO techniques together with some marketing strategies so that as many users as possible can get hold of it.

Also, what you put in your docs should be organized into a structure that makes searching for specific information a breeze. Steve Konves recommends you structure your docs in a singly linked tree: starting from the root node, which should be placed in an obvious location for every interested user to discover, all other items can be easily accessed. The project’s Readme file lends itself to working really well as a great root node for the entire tree.

Also, if you receive help requests from your software’s users, you could write the answers and make them available in an easily accessible FAQs page. Doing so will decrease the time you spend helping users, but it will also give you a clearer idea of the kind of information users need most frequently so that you can document them first and keep them in a prominent place in your docs.

Ensure Your Docs Are Up-to-date and Free of Bugs

Easily accessing your software documentation is great, but if users find out that its content is out of date or the sample code or instructions lead to buggy results, this gets frustrating, to say the least. Still, Steve Konves suggests you keep your docs close to the code — for instance, in source control. This way, when developers update the code, they’ll notice the documentation material, which makes updating the docs a much more likely occurrence.

Also, to minimize the occurrence of bugs, thoroughly test the instructions and the code samples you provide in your docs.

Extra Tip and Some Popular Examples

Don’t stop at documentation. Blog posts are great for making your software and its features known to a wide audience of potential users. Use your blog to offer clarifications of what your product does, deliver user-friendly tutorials, tips and tricks, walk-throughs, explain updates, etc. You can include your blog in a stand-alone website dedicated to your software — perhaps with a forum — around which a strong community can gather and grow.

A great example of this wider idea of documentation in my view is implemented by GreenSock, a widely successful JS animation platform, which I find myself using a lot, not least because its website makes available easy-to-use and well-structured docs, a super helpful forum, blog posts, quick tips, and much more.

React and Vue.js can also be counted as great examples. As soon as you access their respective websites, the home page tells you what each library is good for in a quick tagline, and then goes into more details on why the library can be considered a great choice for your project. Both websites make getting started less intimidating using gentle introductions, illustrative snippets, short tasks beginners can accomplish using code playgrounds, etc. Once users have gained a bit of confidence with the new software, they can find the more technical API docs readily, plus pages detailing how to get help, displaying information on the ecosystem, offering a news or blog section, etc.

To leave the JS zone and go into the field of popular UI libraries with great websites, I can’t leave out Bootstrap. On the Bootstrap website you’ll find right away what the library is good for and how to get started quickly, as well as comprehensive and well-structured docs and a blog to keep users updated on what’s new.

Conclusion

Writing good documentation has its challenges, but it certainly pays off a hundred times if you think how much easier it will be for your users to implement your software’s capabilities. This in turn contributes to your software’s popularity, which makes it attractive and therefore open to the possibility of giving rise to a community of developers who are willing to invest their time in learning it deeply and contributing to its growth, stability, and long-term usage.

Frequently Asked Questions (FAQs) about Writing Software Documentation