search

cujojs / when

A solid, fast Promises/A+ and when() implementation, plus other async goodies.
Other
3.44k stars 396 forks source link

Add docs badge to README #425

Closed rrrene closed 9 years ago

rrrene commented 9 years ago

Hi there,

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

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 Shipit).

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/cujojs/when

What do you think?

briancavalier commented 9 years ago

Hi @rrrene, thanks for making us aware of InchJS, it looks cool. I know you're focused on inline docs, but we also have put in a significant amount of time to our markdown-formatted API docs. We did that mostly because we found that JSDoc, even thought it has come a long way, wasn't really sufficient for generating documentation for a functional-style library like when.js. JSdoc tends to favor OO libs--the default template even hardcodes the category "Classes", for example.

Consequently (and unfortunately), we have less incentive to use inline documentation, and more incentive to write markdown. Have you had any thought about how to handle that situation?

rrrene commented 9 years ago

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: when is seriously good in terms of inline documentation. But even if it wasn't: Most times, any amount of inline-docs is better than none. This badge tries to emphasize that.

briancavalier commented 9 years ago

The idea is to motivate aspiring Node developers to dive into Open Source projects and read the code.

Thanks for explaining, @rrrene. That's definitely a worthwhile goal. Count us in.