The value of the docs badge

I get asked about the “value” which the docs badge provides to project maintainers, in the sense that I ask people maintaining popular projects to include my little badge and they ask back “What do I get out of it?”.

And the blunt answer is: most likely nothing. At least not directly.

Understanding a project’s code is a neccessary step in contributing to open source. I don’t think that “good code is it’s own documentation”, at least not in my day-to-day experience. Because with any sufficiently large, completely undocumented codebase I arrive at the conclusion that I am no Ruby parser. And quite frankly no one should be expected to be one.

Sharing your ideas and code is one thing, but making it accessible to those willing to contribute is another. Zach Holman (who also wrote about the value of documentation and how it helps you in the bedroom) wrote an essay about how Open Source, although it is free (as in beer), has to be marketed to its target audience: “My favorite marketing of all time is documentation.”

With a docs badge, maintainers can signal to people that their project is not completely undocumented. People are more likely to contribute if the code is “easy to get into” or, as Zach sums it up:

Better documentation, […], more project activity, more contributions, happier users. I like it.

The idea behind the docs badge is not to tell people “This is how docs should look like” and to get a fully green bar.

The idea behind the docs badge is to remind people, newbies and veterans alike, that code documentation is an essential part of the sharing process, which makes OSS so great.

That being said: You can get a badge for your own projects on inch-ci.org.