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?).