April 5, 2020

Software Documentation Types and Best Practices

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 localrenopros.

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:

Report Advertisement
  • 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

Leave a Reply

Your email address will not be published. Required fields are marked *