Why coders should prepare good documentation

Get more contributors to your project with better documentation

Posted 26 Feb 2014 by 

10 readers like this
share documentation to code
Image by : 


It is not uncommon to have a cycle of news around communities being unfriendly to women or newcomers or people who aren't already there. By 'news' I mean someone posts something that is close to their heart about some unjustice and other people comment on it or write their own posts and generally, the moral of the story is: But we should be better than this!

This is normal and desired behavior as part of the overall community. This cycle is a good thing because it causes people to think about their behavior as community members and what it's like to be an outsider and how they can improve. These are all positive steps because it springs from an honest desire to be better people. That's awesome.

Beginners in Open Source week

View the complete collection of Beginners in Open Source articles

Lately, I've been poking in areas of technology where I don't tend to tread often. One area has been picking up a new piece of technology by looking at the documentation. This particular journey began by being a Glass Explorer, and that's a story that I've talked about on my own blog at amye.org, so I won't recap it here. But, late one night, as I was churning through documentation on what Android will actually do and all of these (frankly amazing) things that your smartphone hardware has the capability of doing (ambient air pressure, anyone?), it struck me that documentation is one of the great levelers of our time.

Everyone has to read documentation. Everyone. You know those times where you jump in and don't bother to read the manual and then wonder why it didn't work? Well, yes... this happens to everyone. The person 'just downloading to try it out' and the person who wrote vast swathes of the code both have a vested interest in documentation. Granted, there are different spectrums to their interest, but they are both valid. I think of it a little bit like the 3rd grade student who's just learning to read music and the professional pianist who can sightread instantly—but, they both need the score to know what the next notes to play are.

Given that context, your documentation in your open source community says something about what you expect your community to be. I realize that I am going to get plenty of comments about how your code is self-documenting. No, dear sirs and madams, it very much isn't. Expecting your code to be self-documenting is like marking individual trees in your forest without paying attention to where the forest lives. Is this in the arctic? The tropics? What sort of creatures am I likely to find under that rock when I pull it up? What am I looking at and where do I expect to be next?

I'm enjoying working through the Android documentation because it's a platform and it lets you know at nearly every turn. It's clearly defined and laid out, but there are still pieces of the vocabulary that are unfamiliar.

I ran across this tweet by @relsqui a while back and it has stuck with me...

Theory: Lack of documentation promotes impostor syndrome. "I must be supposed to know this already/be able to figure it out on my own ..."

Here's why I've held onto it—it might be a theory but a theory is the highest scientific law, and it's up to us to disprove it. There's plenty that you can do; just keeping a running text document as you get through a project is helpful as well.

Bottomline: If you're not going to document what you did for other people, how about doing it for your future self who will come back in six weeks and not remember where you were going for?


View the complete collection of Beginners in Open Source Week articles.


Luis Ibanez


Thanks for the great article.

For the longest time, we developers, have look at documentation as the "vegetables" of our programming lunch... We know they are good for us...but... :-)

Of course, when it comes to trying to use someone else's code, we do expect documentation to be up to standards, and get quite disappointed when it is not.

The degree of documentation is one of the good metrics that Ohloh publishes in the project factoids. Typically a 20% fraction of comments is a good sign. That is 20 lines of comments per 100 lines of code.

Curiously, documentation is one of the areas where projects can use the help of beginners and newcomers. The rationale is that: if beginners get lost and confused, then our documentation is not good enough. Creating the mechanisms for newcomers to point out flaws and misses in the documentation is a great way to open that dialog and feedback.

Here is an example of what we did in the Insight Toolkit (ITK). Where we use Doxygen (a great documentation tool) to harvest documentation from comments embedded in our C++ code. As part of the web generated pages we added a PHP infrastructure to enable readers to point out flaws in the documentation and to submit them as Gerrit patches, that can right away be code-reviewed, and potentially committed into our ITK Git repository.

Here is an example for the class Array2D:

and the page where a reader could generate a documentation patch:

that will go automatically to the Gerrit review system

The contributor gets full credit for her/his authorship, and everybody wins.

This of course, only covers the technology of the collaboration platform, and must be accompanied by nurturing in the community a culture of:

"Leave the place cleaner than you found it" :-)


Vote up!
Vote down!

That is awesome!
I'm glad you found it helpful!

Vote up!
Vote down!
