How To Document Your Open Source Product

No matter how good your open source software product is on its own, you need to have proper documentation for it to be useful to your end users. As the co-founder of one of the UK’s top WordPress plugin companies, Barn2 Media, I have learned first-hand the importance of documenting your open source products in a clear and comprehensive way.

Here are some of the direct benefits we experienced after publishing good, comprehensive documentation for our open source products:

• Our code became understandable, extendable, and reusable.
• We effectively empowered our customers to use our products and be self-sufficient.
• It allowed us to improve the credibility of our products.
• We were able to reduce support requests over time.

The Perils of Inadequate Documentation

Developers often underestimate the value of having good product documentation. In fact, a lot of the time great open source products, projects, and libraries lack proper documentation. The problem is that inadequate documentation doesn’t help your users realize the full potential and capabilities of your code.

When we started out, we had a single page of documentation for each WordPress plugin. This led to a barrage of support requests and meant that we were spending all of our time providing support. We quickly learned that by providing more complete documentation, we could run open source projects in a more sustainable, less time-intensive way.

Public or Private Documentation?

As the developer behind successful open source products, I always recommend publishing documentation on your public website for everyone to view. As well as making it easily accessible, this is great for SEO and will help you raise awareness about applicable use cases and grow your project.

Preemptively answering the customer’s questions reduces back and forth support questions and helps us deliver good customer experience. What’s more is that it encourages customers to search through the knowledge base before submitting a support ticket.

Make Your Documentation Easy to Navigate

Having proper documentation for your open source project doesn’t mean you should simply add everything to a single page and publish it on your website. This makes it difficult for your customers to find what they’re looking for.

Instead, I’d recommend integrating a public knowledge base into your website that allows customers to run search queries, browse categories and sub-categories, or view a table of contents.

For example, you could have a "General" category with sub-categories for pre-sales questions and FAQs and individual categories for each one of your products.

If you’re using a content management system (like WordPress) for your documentation, you can use a knowledge base plugin such as Heroic Knowledge Base or Posts Table Pro to list your project documentation pages in an accessible, searchable layout.

For those of you who aren’t using a content management system, I’d recommend opting for a hosted support and ticketing system that comes with a built-in help center. Help Scout and Zendesk are popular offerings in this space.

Cater to Different Learning Styles

Everyone has different learning preferences. Some people find it easier to read a tutorial whereas others would prefer to watch a video demonstration.

Since everyone learns differently, it’s important to include as many kinds of instructions as possible. On Barn2 Media, for example, we provide written instructions, embedded video tutorials (e.g. YouTube videos), and animated GIFs showing specific features of our open source software:

Conclusion

Writing documentation for your open source project is an on-going process. Based on my own experience, I would advise developers to spend some time putting together the best possible structure for their product’s documentation.

This way, you’ll be able to add articles, videos, and tutorials to it whenever you receive a new, unique support request from your customers. And whenever you’re asked a question that you’ve previously answered, you can quickly direct your customers to the relevant article in your knowledge base.