Code Documentation, Streamlined — Smashing Magazine

Everything about software documentation is difficult – from allocating time to do it to keeping it up to date. Documenting success is difficult to achieve, and often there is not enough time to measure impact. This is because they do not bring a tangible impact on the end-user experience. We are unable to value good documentation. Therefore, it is not uncommon for the efforts to create and maintain delightful documentation to outweigh the time investment and proper planning.

Penny or Dime

Software developers are busy writing code and content (well, most of us ). We can easily justify our salaries when compared against the features we ship and the revenue they generate. So when it comes to writing and educating our peers about those features so they are more able to interact with their code, we often question the value of those minutes as opposed to shipping the next feature or getting around that nasty bug to fix There is so much technical debt, so why write about code we have to refactor?

We save those minutes instantly — it’s an obvious choice. Right back to code. And we just saved ourselves a few pennies of time. Fast forward a bit; a colleague must jump in and implement a change. You’re out (working on the...