Darrell's Braindump

Documentation Driven Engineering

tags
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.