Where there’s an open source project, there’s bound to be documentation. But the question is, is it great documentation, or is it just “good enough”?
Documentation can often fall in the latter category, mainly because it isn’t given the proper respect and recognition that’s due. While documentation may not be considered the “meat” of a project, it certainly plays a significant role. Without it, you’d hardly have any users and contributions would cease to exist. And even if it is present, if it is not crafted well, it still won’t be effective in encouraging users and contributors.
It’s important therefore, not just to create documentation but to make it exceptional. Any less and it will fail to fulfill its purpose, which is to easily guide users and encourage them to use, share, adapt and contribute to the project.
In order to create great documentation, we must first define exactly what this “greatness” means. So what are the characteristics of great documentation?
The very nature of open source means that projects ought to be open to anyone who wants to use or change it. Documentation must therefore be as inclusive as possible. This means using simple, easy-to-understand language, making sure final docs are in the formats most users are familiar with and require, and offering clear invitations and opportunities for contributions.
Great documentation is not just read, it is easily understood and applied. To that end it needs to exhibit the three C’s : clear, consistent and concise. You have to use clear, unambiguous terms and keep the phrasing as simple and concise as possible. The less time readers spend trying to figure out what you’re saying, the more time they can work with your software and make meaningful contributions. It also has to be consistent: in word choices, in markup style and writing style. Apart from these three C’s, it’s important to offer documentation that’s less mechanical and more conversational, such as FAQs and blog posts. Offering samples and screenshots also goes a long way to making your documentation more user-friendly.
The best documentation is one that doesn’t need further clarification. One sure way you can achieve this is to test your documentation or better yet, have it tested by a beginner. By testing it you can check which areas are unclear, missing or don’t achieve intended results.
Aside from being accommodating to current users, great documentation considers the needs of future users. This means that you should keep word choices consistent to make future translations more efficient, be open to feedback and provide updates whenever it is needed.
These are just some of the most common characteristics of great documentation. In the end however, what really defines great documentation is how well it is able to attract contributors, enhance the quality of the code and grow the community.
What other features do you consider pivotal in great open source documentation? Share your thoughts in the comments section below.