Add docs badge to README

[rrrene]

Hi there,

I want to propose to add this badge to the README to show off inline-documentation:

The badge links to Inch CI and shows an evaluation by InchJS, a project that tries to raise the visibility of inline-docs. Besides testing and other coverage, documenting your code is often neglected although it is a very engaging part of Open Source.

So far over 500 Ruby projects are sporting these badges to raise awareness for the importance of inline-docs and to show potential contributors that they can expect a certain level of code documentation when they dive into your project's code and motivate them to eventually document their own. I would really like to do the same for the JavaScript community and roll out support for JS over the coming weeks (early adopters are forever, node-sass and when).

Although this is "only" a passion project, I really would like to hear your thoughts, critique and suggestions. Your status page is http://inch-ci.org/github/duojs/duo

What do you think?

[stephenmathieson]

i dig the concept, but we've already got fairly decent (imo at least) docs at in ./docs

[rrrene]

Thanks for considering! Unfortunately none-inline-docs are not the focus of my little project. On the chance that I lose your interest for good, let me elaborate:

This badge is not really about showing off how good your documentation is or getting to 100%, which is why there are no numbers on it. And it certainly is not about bragging "Look at my perfect docs!"

The idea is to motivate aspiring Node developers to dive into Open Source projects and read the code. It is about engagement. And for me, while testing and code coverage are important, inline-docs are the humanly engaging factor in Open Source. This project is about making people less adverse to jumping into the code and see whats happening, because they are not left alone while doing so. I know that, because I put off reading other people's code way too long in my life.

And let me be clear: duo is seriously good in terms of inline documentation (the bar is green after all, partially deep green even). But even if it wasn't: Most times, any amount of inline-docs is better than none. This badge tries to emphasize that.

[matthewmueller]

I like this idea as well, but I really don't like the badge :-/. What's the progress bar represent?

[rrrene]

The badge shows the amount of inline docs present in the project and how documented and undocumented parts relate to each other. To give another example:

(taken from cujojs/when)

This tells me that more than half of the code is documented, there is a good chance I can jump in and find helpful annotations as to "what's what".

Regarding the bar and it's segments:

• Darker green means "can not suggest any improvements"
• Normal green means "good docs, can suggest minor improvements". So one can see at a glance "this is documented pretty good".
• The not-filled-part of the bar represents undocumented code, which in case of when are all self-explainatory functions (which is the main reason why it is always fine to have some undocumented parts in a codebase).

I, of course, hope to persuade you to include this badge in Duo's README because I see value in it and I think it provides value for project maintainers as well (that blog post was written for the Ruby version of Inch).

[rrrene]

@MatthewMueller that you really don' like the badges is very unfortunate for me :wink: since you seem to value inline-docs at least as much as I do and would be a great "testimonial" for the topic:

MatthewMueller/date MatthewMueller/array

[matthewmueller]

It's really just the colors, haha. What about something more like this in terms of colors and style: https://dribbble.com/shots/1755870-Assembly-Brand-Elements?list=searches&tag=bars&offset=49

[dominicbarnes]

I don't think we're gonna move forward on this, so I'll close this issue.