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.
Key Takeaways
- Good software documentation is crucial for user adoption and understanding, serving as a communication tool between developers and users. It should include tutorials, how-to guides, reference guides, and explanations, providing a comprehensive guide to the software’s capabilities.
- The target audience for documentation should be clearly identified, as this will shape the content and language used. In the context of this guide, the focus is on documentation for developers of varying familiarity with the software, rather than user manuals or project documentation.
- Documentation should be easily discoverable, well-structured, and regularly updated. It’s recommended to keep documentation close to the code, in source control, to ensure it remains relevant and accurate as code updates occur. Including an FAQs page can also help address common user queries.
- Beyond traditional documentation, blog posts can serve as a useful tool for explaining software features, providing tutorials, and sharing updates. This can foster a community around the software, contributing to its growth and success. Examples of good documentation practices can be found in platforms such as GreenSock, React, and Vue.js.
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:
- 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.
- 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
What are the key elements to consider when writing software documentation?
When writing software documentation, it’s crucial to consider the target audience, the purpose of the document, and the type of documentation being written. The language used should be clear, concise, and easy to understand. The document should be well-structured, with a logical flow of information. It’s also important to include visuals like diagrams or screenshots where necessary to aid understanding. Lastly, always ensure the document is thoroughly reviewed and edited for accuracy and clarity.
How can I make my software documentation user-friendly?
To make your software documentation user-friendly, use simple and clear language. Avoid jargon and technical terms as much as possible. If you must use them, ensure you provide clear definitions. Organize your content logically and use headings and subheadings to make it easy to navigate. Include a table of contents and an index for longer documents. Use visuals like diagrams, screenshots, and videos to illustrate complex concepts.
What are the different types of software documentation?
There are several types of software documentation, including system documentation, user documentation, and technical documentation. System documentation provides an overview of the software system, including its architecture and data flow. User documentation provides instructions on how to use the software and includes user manuals and help guides. Technical documentation is intended for developers and includes code comments, API documentation, and development guides.
How often should software documentation be updated?
Software documentation should be updated whenever there are significant changes to the software. This could be due to new features being added, existing features being modified, or bugs being fixed. It’s also a good idea to review the documentation periodically to ensure it’s still accurate and relevant.
What tools can I use to write software documentation?
There are many tools available for writing software documentation, including word processors, documentation generators, and specialized documentation tools. Some popular options include Microsoft Word, Google Docs, Doxygen, and Sphinx. The choice of tool depends on your specific needs and the complexity of the software.
How can I ensure the quality of my software documentation?
To ensure the quality of your software documentation, always review and edit your work thoroughly. Consider having a colleague or a professional editor review your document. Use a consistent style and format throughout the document. Ensure the information is accurate, up-to-date, and relevant. Lastly, consider getting feedback from users to identify areas for improvement.
What is the role of visuals in software documentation?
Visuals play a crucial role in software documentation. They can help illustrate complex concepts, making them easier to understand. They can also break up large blocks of text, making the document more readable. Examples of visuals include diagrams, screenshots, flowcharts, and videos.
How can I make my software documentation more engaging?
To make your software documentation more engaging, use a conversational tone and active voice. Break up large blocks of text with visuals and bullet points. Use examples and case studies to illustrate concepts. Include interactive elements like quizzes or exercises where appropriate.
What is the importance of consistency in software documentation?
Consistency is important in software documentation as it makes the document easier to read and understand. It also gives the document a professional look and feel. Consistency applies to language, style, format, and visuals.
How can I improve my skills in writing software documentation?
To improve your skills in writing software documentation, practice writing regularly. Read other software documentation to learn from them. Take courses or workshops on technical writing. Seek feedback on your work and be open to criticism. Stay updated with the latest trends and best practices in software documentation.
Maria Antonietta Perna is a teacher and technical writer. She enjoys tinkering with cool CSS standards and is curious about teaching approaches to front-end code. When not coding or writing for the web, she enjoys reading philosophy books, taking long walks, and appreciating good food.