Raising the visibility of inline-docs
Wait, docs?
Documentation is a great way to communicate your thought process, documentation makes for more testable code and documentation is marketing. Zach Holman wrote and talked about this and he is right.
This is why I wrote Inch, a documentation measurement tool for Ruby. It was a good first step in making documenting your classes and methods a bit sexier, but it has one big disadvantage: it is not visible to the outside world.
To truly raise the visibility of our projects’ docs, we need a way to announce their existence to the outside world, to show people that any amount of inline-docs explaining their thoughts and reasoning is better than none.
Introducing Inch Pages
Let me introduce you to Inch Pages, a GitHub pages powered, first step in that direction.
It provides badges for READMEs and status pages to show the world that you documented your code. Like Inch, the badges do not show coverage numbers, but a spectrum of documentation quality to emphazise the concept of “even some docs are better than none”.
Because, let’s admit it: Badges are cool. They give you the big picture:
Tests passing - Code Quality on par - Docs are there
Combined with the well known badges from Travis, Code Climate, et al. these docs badges allow you to tell the whole story. So get your own badge today!
Okay, I got it. Let’s start a competition!
Well … achieving a fully green bar is not the goal. It is to show that documentation is copywriting for hackers and that having some inline-docs is always beneficial.
Take Rails for example, which is documented fairly well: 
It seems Rails’ source is not fully documented with inline-docs. And that is more than fine, because I don’t think they have to
document straight-forward methods like ActiveRecord::Migration.load_schema_if_pending!.
So is this a fully featured CI service?
No, not yet at least. This is a community driven project based on GitHub Pages, passion, pull requests and a bit of manual labor on my part (explained here).
Inch Pages is a social project at heart. We can always implement a full-blown web-service after we have convinced a broader audience of the importance of inline documentation.
But for now, the important bits for raising the visibility of code documentation are there: badges and status pages.
What can I do?
Well, you can request a badge for one of your projects.
Besides that: Let’s talk, let’s start a discussion! This project needs feedback.
You can find me on Twitter, create an issue in the Inch Pages project or simply email me (mail in Github profile).
I am really looking forward to it!
