Raising the visibility of inline-docs24 Feb 2014
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.
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
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.
I am really looking forward to it!