GROWS logo

Write It Down

Summary

Write down technical decisions in an Engineering Log. This can be an electronic record, or in a paper journal. Keep dated, brief notes on architecture and infrastructure ideas: who was there, what alternatives are being considered, the reasons for accepting one idea over the others, exterior forces that influence your decision.

Pain

  • Your team and leaders get into arguments over why earlier decisions were made.
  • Team members recall important events differently.
  • Constraints have changed and you need to revisit fine details of earlier decisions. But no one remembers the details.

Benefits

An Engineering Log helps the team retain an accurate, corporate memory.

Decisions are generally the best decisions given the information available at the time, but things change. Later, when the situation has changed, you can refer back to the alternatives you had considered and re-evaluate if they might make a better choice now.

You can also use the Engineering Log to support earlier decisions when challenged and help show that any previous decision was reasonable given the information known at that time.

While version control keeps track of code and deliverable assets over the lifetime of a project, an Engineering Log keeps track of the thought process that went on over the lifetime of the project, and especially the alternatives that were not taken.

Application

❑ Critical ✓Helpful ❑ Experimental

Feedback Sources

When a question comes up as to why something was done a certain way, you can go back to the engineering log, find the appropriate entry, and understand why that decision was made and who was involved.

Adoption Experiment

Steps to first adopt this practice:

Setup

  1. Chose a journal format: paper, electronic, etc. It needs to be something you’re comfortable with, and will always have access to when in meetings or design sessions.

Trial

  1. In each meeting or informal design session, jot down a few quick notes documenting any “important” decisions. Of course, it can be hard at the time to differentiate something that might be important later. When in doubt, just jot it down anyway.
  2. Each Monday morning, review the last week or two worth of notes as a quick refresher.

Evaluate Feedback

  1. Two weeks after your first entry, go back and review your earliest entries. Did you capture the important essence of these decision? Is it too soon to tell?
  2. When a disagreement comes up, or a sudden surprise, is the log helpful?
  3. If something comes up and the log was not helpful, what could you have done different? Did you miss something you should have written down? Would that have helped? Can you do it differently next time?

What Does it Look like?

  • All entries are dated, and there is some indication of who was involved.
  • Entries are quick and concise.
  • Repeat the log entries back to the team to make sure they are accurate and that everyone at least starts off with the same memory.

For example:

January 27: Fred and the Marketing dept. says all customers will be on SQLServer, so we will exploit SQLServer-specific extensions for better performance.
...
August 13: New customers are all on Oracle, so we will remove the SQLServer-specific extensions.

But then Sara notes that it’s not just Oracle, but many new customers are using Postgress. The log will be amended:

August 13: New customers are all on Oracle, Postgress, and other databases so we will remove the SQLServer-specific extensions.

Warning Signs

You’re doing it wrong if:

  • You’re spending a lot of time making entries in the log.
  • The log is missing entries for crucial decisions.
  • Everyone’s log describes the same event with very different outcomes; there’s no consensus.

Growth Path

In the beginning, record all decisions, no matter how seemingly trivial. If it was enough of a decision to warrant a meeting or discussion amongst several team members, then it’s probably important enough to jot down. The level of detail and alternatives will be about the same for all decisions.

But over the time, you’ll better recognize which decisions are shakier, and may well be revisited in time, and which are more stable and not likely to change. You’ll record more detail and helpful pointers (URLs to information and code resources) for the more difficult decisions.

Exercises to Get Better

Keep a personal “tips & tricks” log. Add in new things you’ve learned, useful tips and tricks, code recipes and pointers to useful websites, etc.

How to Teach This Practice

Sit in on the Daily Team Sync (known as the “stand up meeting” in Scrum) and take notes for what your experience thinks might be relevant for the team. Read it back to them after the sync.

How To Fail Spectacularly

This practice is pretty straightforward, and unless you spend too much time taking notes (you’re not writing War and Peace), or not taking any notes at all, it’s hard to go too far wrong. However, if you have any great stories to share, please let us know.


←Prev (Work from a list)(Checklist for Individuals (Stage 1)) Next→

Follow @growsmethod on Twitter, or subscribe to our mailing list:

Sign up for more information on how you can participate and use The GROWS Method™. We will not use your email for any other purpose.