#160 - feb 28th 2016

Rant

About tests and documentation

This aspect of development, called Documentation, is the source of various frustrations. It's hard to get do it, but why? My feeling is that it's like testing. When you begin your craft as a coder, all what matters is the code. It's only after some iterations that some non-code aspects come back bite you in the neck. Like, huho, now that I need to refactor, I really should use something that tells me if all still works. Tests become an early necessity to anyone who knows that kind of truth. If you wait until the end of a coding cycle to write those, the task is huge and it cuts you from your productivity cycle. Write them early, along the flow, is way easier.

So I think documentation follows the same pattern. So many software projects are badly documented because this aspect is postponed until it's needed. Means at release stage. In early stages, you work on a prototype and you don't need to explain how things work or are supposed to work. And when it's released, there is usually some other task waiting and it's hard to stop everything to get back and document things properly. It may be a flaw in the agile process, but it may also be a feature: if you don't document along the way, you won't document much.

Personally I try to consider the documentation of any of the source code I write as one of the first tasks. There are various tricks that can help in that perspective, like readme-driven development, or including the doc inside the code with yarddoc or apipie, or coupling documentation with tests with rspec or RSpec API Doc Generator. But honestly I prefer edited documentation that can follow a structure that is thought as documentation rather than merely an automated output of some code.

There are various tools to organize edited documentation, like ReadTheDoc which is in python. Another project appeared last week from the guys at Pluralsight named hack.guide(). That's a community project but actually being totally open sourced, I was thinking the documentation building CMS they made could pretty much fill the gap of a light-weight RTD, with the benefits of having a UI for editors. Too bad we don't have anything like this in ruby (or do we?).