Notes To Future Self Revisited

There’s a hole at the heart of current Agile practices which many thoughtful professionals are keen to fill.

June’s post elicited a ragged applause along with a couple of grudging thumbs-ups. All the same, it seems to me that many in IT have forgotten what we’ve known since the Sumerians first applied reed wedges to clay tablets: that when we write things down we can lock up the present and open the future.

Recorded information extends our knowledge not only beyond those people we can interact with face to face (“Individuals and interactions over processes and tools”), but allows us to communicate forward in time as well laterally to ourselves and to our colleagues, and to our distant colleagues.

Developers and engineers at some of the leading tech organisations know there is a problem.

Here’s Eli Perkins from GitHub recommending the rationale behind the use of Architecture decision records (ADR) by the mobile team:

• They’re not for you, they’re for future you
• They’re not for you, they’re for your peers
• They’re not for you, they’re for your future peers

Similarly, Google’s Malte Ubi recommends the problem solving utility of design docs:

Besides the original documentation of a software design, design docs fulfill the following functions in the software development lifecycle:

• Early identification of design issues when making changes is still cheap.
• Achieving consensus around a design in the organization.
• Ensuring consideration of cross-cutting concerns.
• Scaling knowledge of senior engineers into the organization.
• Form the basis of an organizational memory around design decisions.
• Acts as a summary artifact in the technical portfolio of the software designer(s).

Malte even provides a simple sample design doc structure .

Finally, here’s Gergely Orosz describing the planning process Uber engineers use - Scaling Engineering Teams via RFCs: Writing Things Down . He makes the point that knowledge written down (documents) extends the visibility of information, particularly when there is a formal process around it (in other words not just a discussion in an IRC chat channel.) Specifically:

Writing and sharing that writing with others creates accountability. It also almost always leads to more thorough decisions.

Writing things down doesn’t have to be complicated. Simple, repeatable processes work. They save future time and future cost for future self and future colleagues.