trivelop   home of @rrrene   –  

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:

Build Status Code Climate Inline docs 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).

Fork me on GitHub