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.

The post A Guide to Writing Your First Software Documentation appeared first on SitePoint.