Documentation Driven Engineering
It’s an age-old addage that code should be self-documenting. But is that just a well-intentioned urban myth?
There’s a useful, if not overly-simple rule of thumb that I use when thinking about the process of software engineering; Parts A, B, and C.
Part A is the process of information gathering, hypothesis forming, and perhaps most importantly, writing it all down somewhere.
Part B is when I’m at my best. Writing code, wiring together software, and making things work.
Part C is after I’ve shipped my creation to users on the real internet, and the monitoring and care required for support.
Admittedly, I find myself spending way more time in B than I ever do A or C, and I have a feeling that I’m not alone.
This leads me to the greater point of this thought, which is that part A needs more attention. The part where we’ve written down the problem and maybe even vocalized a few solutions before any code is written.
In this part we’re able to think about “why” we’re building the things we’re building, and do some early solutionizing in a code-free environment.
I love using the DACI model for very early, code-free solutionizing. It feels alot like community brainstorming.
These early documents serve as the spring board for the real project documentation, and help with communication to external stakeholders.