“Writing is nature’s way of letting you know how sloppy your thinking is.” Richard Gordon Guindon.
Everyone recognizes that the pace and pressure of building new products to aggressive deadlines pushes the documentation requirement to the back of the queue as “non-urgent”. Agile methodologies exacerbate the problem and, to a certain extent, normalise it by de-prioritising the documentation process.
Marc Brooker, lead engineer at AWS Lambda, notes in his blog that Code only Says What it Does , not Why or How. He quotes Leslie Lamport (creator of the TLA+ specificaiton language) who quotes the cartoonist Guindon (above).
Ignore recording your design decisions at your peril, he says:
“Documentation is uncool. Most software engineers seem to come out of school thinking that documentation is below them (tech writer work), or some weird thing their SE professor talked about that is as archaic as Fortran …. What I discovered later was that design documentation, encoding the intent and decisions made during developing a system, helps teams be successful in the short term, and people be successful in the long term. Freed from fitting everything in my head, emboldened by the confidence that I could rediscover forgotten facts later, I could move faster. The same applies to teams.”
Be nice to your future self, so that you remember why you did what you did.