[Reading Time: 1 minutes 19 seconds]
One of the great things about writing code is that it allows you to preserve information that might otherwise be lost.
Especially if you’re building infrastructure, which traditionally meant writing readmes or other kinds of documentation that gave an inkling of what needs to be done.
But of course there are lies, damn lies, and documentation: you can be sure your documents will be out of date, and incomplete (turns out it’s really hard not to miss a step, particularly the ones that seem obvious to you).
This may sound like a trivial issue (comments never solved any problems, code does – right?). But it isn’t.
Because the opposite is true: documentation solve lots of problems, or perhaps more often makes them not even exist in the first place.
Why?
Because all code’s purpose is to share information between humans (if that weren’t the case, we’d all be writing machine code).
So all code is documentation – except it’s the best kind: it’s testable, demonstrably correct and complete.
It’s very clean communication – and clean communication is the foundation for people working together effectively and creating great products.
This is why I insist that all things that a developer might conceivably do, be doable through a single call to something – a Makefile or whatever else you find convenient.
This isn’t automation, even if it looks that way.
It’s active QA: through communication, and preserving information.