Inch Pages: The first three weeks

It has been three weeks since Inch Pages started.

For those who haven’t checked it out yet: Inch Pages is a project to raise the visibility of inline code documentation in Ruby projects. It provides a badge to show potential contributors that the project is documented:

Docs FTW!

As of this writing 53 projects have joined and are sporting these badges in their repos. There are already some proverbial “gems” in there:

archivist-client CanCanCan capistrano_mailer cequel Commander concurrent-ruby csv_pirate dry_views easy_type FiniteMachine flag_shih_tzu gem_bench grape Guard Haml hello_sign helpful-web hydra_attribute Inch java-properties kaminari lego_nxt libnotify Lotus::Controller Lotus::Router Lotus::Utils minicron MiniMagick minitest-around Mustermann naught ndfd-weather-forecast-client on page_record phony PRY PublicActivity rack-insight Reek ROM Rubocop sanitize_email sequential_file SimpleForm softcover sparkr stackable_flash transitions Twitter unitwise Virtus viverelajacion winged-couch

The response has been overwhelmingly positive, for which I am very grateful. I had lots of insightful discussions with you folks and most of them have let to changes that made Inch better. I sincerely hope we can continue to do so.

That said, Inch was also met with caution and scepticism. I will always remember one fellow developer who told me that deciding what to document is a developer task and “not for a machine to decide”. (of course I see his point, but this Skynet-esque reference to my little tool made me smile all day)

The point of Inch Pages is not to achieve a fully green bar. It is to show a larger audience that documentation is copywriting for hackers and that having some inline-docs can only be beneficial. Inch is a tool designed to help you with that.

@solnic said it best in Common Pitfalls Of Code Metrics:

Code metrics and code metric tools can be both helpful and harmful. The difference […] is learning to interpret the results and use the feedback to improve yourself and your code.

TL;DR no worries, the machines aren’t rising (yet).