Write It Down

Summary

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

Pain Points

  • Your team and leaders get into arguments over why prior 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

  • Retain an accurate account of decisions and actions
  • Ability to refer back to previous alternatives and re-evaluate
  • Support prior decisions when challenged; show the information known at that time
  • Tracks the thought process that went on over the lifetime of the project, and especially the alternatives that were not taken

Assessment

  • When revisiting a prior decision, you can determine why it was made and what the context was at that time (Significant Boost)
  • When evaluating a new technology, you can easily determine if you’ve looked at it before, and what your opinion was at the time (Boost)
  • You do not know why a previous decision was made (Setback)
  • You do not know if anyone has looked at a given technology previously (Setback)

Application

✓ Critical ❑ Helpful ❑ Experimental

Adoption Experiment

Steps to first adopt this habit:

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, jot it down.
  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, does the log help?
  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 dep. 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 Postgres. The log will be amended:

August 13: New customers are all on Oracle,
Postgres, 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 involve more uncertainty, 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 Habit

Sit in on the TeamSync 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 habit 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 treat this as a cookbook type task and do it because someone said it was a good idea, and then never reference that information again, you’ve succeeded in failing spectacularly.

  ←Prev (Tracer Bullet Development)(Adopt Personal Learning Habits) Next→

Find Out More...

Follow @growsmethod in the Fediverse, 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.