Note To Future Self

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.

Writing is nature’s way of letting you know how sloppy your thinking is.
Richard Gordon Guindon

Marc Brooker, lead engineer at AWS Lambda, notes in a recent blog post that Code only Says What it Does , but not why or how. He quotes Leslie Lamport (creator of the TLA+ specification language) who himself quotes the cartoonist Guindon (above).

Ignore recording your design decisions at your peril, says Brooker:

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 …

He goes on:

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 later, when you revisit what you did, you can remember why you did what you did.