The Anatomy of a Great Open Source Documentation: How to Document Your Projects on GitHub

But does that even exist? A great open source documentation, I mean...

One that's clean, written with the end user in mind, well-documented, well-presented, actively-maintained and... the wishlist could go on.

It does! And still, these flawlessly-documented open source projects are as rare as unicorns on GitHub.

So, why not add yours, too, to this “highly exclusive club”? Why not capitalize on this chance to make your own project “shine” in the open-source world?

For, the more solid your docs are:

  • the more understandable and reusable your code gets
  • the more developers will want to contribute to your project' further growth
  • the more empowered will the total beginners (e.g. designers who want to understand the codebase) feel to use your software
  • the more credible your project will get, building its reputation on GitHub

But, let's not beat around the bush anymore and, instead, let's deconstruct a good open source documentation into its 5 essential parts:

 

1. The Anatomy of a Great Open Source Documentation 

What is good documentation? And how should you properly document an open source project?

Here are the 5 key component parts of an “ideal” documentation, accompanied by a handful of useful tips for writing each one of these docs:

 

1.1. The Readme File

Imagine it as your project's “storefront”.  

It's the Readme file that users will interact first when they decide to check out your open source library. 

Make it informative, make it brief, make it incentive enough for them to keep on digging through all the other docs in your documentation, as well.

Helpful tips for writing this part of your documentation:

  • can't “squeeze in” content into one and a half pages? How about adding a table of contents, then?
  • make it clear for your users in what way your software can help them; point out the challenges that it helps them overcome
  • list some of its most common use cases 
  • include a sample of code (if it's an excerpt from a real use case of your library, even better)
  • detail the installation process and run an inventory of all the dependencies and prerequisites required
  • keep in mind to add a license, as well, and to list all the contributors
  • add a paragraph where you point out how precisely anyone interested could contribute to your open source project

     

1.2. The Reference File

A key component of a great open source documentation. And, without question, the most technical doc, as well.

It's in this file that you should properly document:

  • all the functions in your software and how they work
  • what inputs and outputs its users should expect
  • … and side effects, too
  • your project's main goal(s)
  • examples of implementation & uses

Useful tips to follow when writing your Reference file:

  • you might be tempted to go with one of the many available solutions that would automate all tasks related to the Reference file: do keep in mind that a computer-generated doc will never be as user-friendly as one including your own explanations
  • a reasonable compromise would be to include at least a one-sentence-long explanation of your own for each item
  • consider adding a link to the function implementation from your software's code (some developers might be interested in how precisely a specific function is implemented)

     

1.3. The Guide File

A tutorial-like document that “takes the user by the hand” and loops through all the features of your software.

Note: it goes without saying that if it's a large, general-purpose library that you're sharing on GitHub, this is going to be the heaviest file in your documentation.

Tips and tricks:

  • first, state the goal of your open source project
  • ... as well as the prior knowledge, specific hands-on experience with certain technologies and skills that users should have for using your piece of software
  • explain how each system should be installed
  • insert code samples and even diagrams and pictures, if relevant
  • try to strike a balance between the “self-explanatory clean code” trend and the “code-commenting” style
  • … and do keep in mind that your users should be able to easily copy, paste and use chunks of your code
  • … as well as get “enlightened” by code comments on how certain public functions work

… this way, they won't need to dig deep into the library source code for answers

 

1.4. The Cookbook File

Another key component of a great open source documentation. 

Take it as a collection of:

  1. “how to's” addressing some of the most common issues
  2. self-contained “recipes” for how to use the library to accomplish specific tasks

Tips on writing a clear, well-documented Cookbook file:

  • detail the features needed for tackling specific problems
  • support your choice of those particular language features with arguments
  • it's always a good idea to highlight your software's integration with other libraries, as well; include links to other docs
  • consider including incorrect code samples and exposing inappropriate use cases of your code, too

     

1.5. The Blog Post 

One of those unnecessary elements that make the difference between a good and a great open source documentation...

Note: you can write it in a GitHub Gist and include a link to it in your ReadMe file; it's not mandatory that you have a blog for writing your blog post.

This is that part of your documentation that answers the “why” question your users will legitimately ask themselves:

“Why was this library needed in the first place?”

What was the context/your motivation? What problems does it solve?

And also:

“Why this particular library over other similar options?”

Helpful tips:

  • write about that challenge you faced that determined you to write this software 
  • explain in what way it is different from other libraries addressing the same challenge(s)
  • also, clearly point out its best uses cases, as well as the types of projects that it's not the best fit for

     

2. The 3 Questions Your Open Source Documentation Should Answer


2.1. “WHY Would I Use It?”

What is good documentation? One that doesn't fail/overlook to explain why that specific library was written in the first place.

Make sure to detail a bit on the context and goals of your open source project!

 

2.2. “WHAT Are Its Functions and What Do They Do?”

A great open source documentation includes detailed (technical) information about:

  • the project's components and the way they interact with one another
  • its functions and low-level data types 

     

2.3. “HOW Do I Install this Project and Use Its Code?”

“How to properly document your open source software?” By answering all the “how” questions that its potential user might ask himself/herself:

  • “How do I get the code running?”
  • “How do I use this library to solve the specific problem that it addresses?
  • “How do I use it to build a basic application?”

     

3. What Makes for Good Open Source Documentation? Few More Tips 

Now that we've:

  • reviewed the essential parts of an ideal documentation for an open source project
  • highlighted the 3 main questions that it should answer to

… allow me to add another handful of helpful tips for writing docs that truly empower the users:

  • check, double check... and then run some more checks to make sure your code examples are working!!!
  • write your documentation for total beginners and from a total beginner's perspective
  • it's always a good idea to use an open source documentation tool; this will help you and all the future contributors track the revision history 
  • remember to set up a “contributing” file, where you explain exactly how anyone could start contributing to your project
  • proofread your docs!!!

The END! And this is how a great open source documentation gets written. 

Is it a bit clearer for you now how to write docs that truly empower the users and... help your project shine on GitHub?