Why Open Source libraries are missing documentation

Sandro Maglione

Sandro Maglione

Free thinking

The primary key to success for any open source library is having a great documentation. If you ever found yourself implementing and releasing your own open source library (like I do ✍️) you may know how the process works.

You, the developer, work countless hours on your own "project". You create everything. You know by heart every single line of code. One day you decide that to make the world a better place, you must release your project to the public, the "Open Source" dream.

Nonetheless, your project is not ready for "production". So you put more and more hours to make the code decent, addressing things like performance, abstractions, security.

After this brutal process, you literally know your code like as if it was your child. You designed it, you created it, you grew it. And finally the day comes in which your "child" is a grown man and you release it for the world to use.

Wait, there is a missing step here. Documentation.

Why documentation is a pain

We all know too well all those amazing libraries that are not usable. If only they had some documentation that tells you what they do...

Have you ever thought about why good documentation is so rare?

Being an Open Source developer as I am is fun and rewarding (most of the times). However, in the lifecycle of an Open Source project the "fun" tends to dwindle as time passes.

You experience the absolute peak of excitement the first day when you finally decide to work on a new shiny project. After that your excitement slowly but steadily fades away over time.

Most of the projects are never completed because the joy of working on them vanished before they are ever released

The ones that survive until release need to cope with another much more fearsome monster, documentation!

Think about it: you pushed through for hours and hours to "complete" the implementation of your project. You want to be able to feel the satisfaction of hitting the release button. Everyone is telling you that documentation is crucial for your library if you want people to use it. However, the mind of the developer is thinking different thoughts at this stage:

  • The library works, I can always add more documentation later
  • The code is easy and the project structure is easy to read and navigate, so people will be able to understand things anyway
  • The community will help to write the documentation after they start using my library
  • The library is solves a really useful problem, so people will work hard to learn how this works even if the project lacks documentation

It all makes sense in the mind of someone who spent the last 3 months single-mindedly working on one codebase.

In reality though, things are a little different:

  • The library works, and I already spent 3 months of my time on it. Documentation? Give me a break!
  • The code is easy and the project structure is easy to read and navigate for someone who spent 3 months on it. For everyone else, it's garbage.
  • No one will use the library, so no one will contribute to documentation. Even if someone is ever able to decipher this monster, it will be too late. They too will going th dark side of "the code is easy and the project structure is easy to read and navigate, so..."
  • The problem may indeed be painful, but people prefer to work countless hour on their own "solution" instead of having to deal with yours

How to solve the documentation problem

Of course not all projects are doomed, otherwise we would not have the amazing ecosystem of Open Source at all. Solutions exists to solve the Documentation Problem™.

However, every Open Source developer must recognize that there is not escape from actually writing docs. Some possible solutions may be:

  • Write documentation incrementally
  • Start from documentation, using it to define the requirements of the project before implementation. This may also be a good idea to verify that your solution actually solves a real problem
  • Comment the code (not really a solution, but possibly a step in the right direction)
  • Do not solve it, just release it for yourself and call it a day

Real World example

fpdart is an Open Source library I developed to bring Functional Programming in dart. Like many other libraries out there, fpdart started as an experiment. I had a problem, I wanted a solution.

After a long initial researching phase (no code here), I realized that this thing was possible and I started actually implementing the library.

I kept in mind the idea of documentation from the beginning. My primary concern was to write documentation comments all throughout the codebase.

Documentation comments allow a user to hover any method/function on the IDE and see an explanation of what that specific method does

My idea was that you could use the awesome tooling available in the dart ecosystem to navigate the library without reading a lengthy documentation.

IDE tooling for fpdart

The second step I took was to design a readable and extensive README.md file for the repository. This file is the first thing a user of the library will see, so it is important to make a good impression.

The third step is to write blog posts and implementing real world app examples. This process is always ongoing:

  1. Fpdart, Functional Programming in Dart and Flutter
  2. How to use fpdart Functional Programming in your Dart and Flutter app
  3. Pure Functional app in Flutter – Pokemon app using fpdart and Functional Programming
  4. Functional Programming Option type – Introduction
  5. Chain functions using Option type – Functional Programming
  6. Practical Functional Programming - Part 1
  7. Practical Functional Programming - Part 2
  8. Practical Functional Programming - Part 3

If you are an Open Source developer, remember to write documentation.

If you are a user, remember to contribute if you get the chance.

👋・Interested in learning more, every week?

Every week I build a new open source project, with a new language or library, and teach you how I did it, what I learned, and how you can do the same. Join me and other 700+ readers.