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 were being considered, the reasons for accepting one idea over the others, exterior forces that influence your decision.
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.
❑ Critical ✓Helpful ❑ Experimental
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.
Steps to first adopt this practice:
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 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.
You’re doing it wrong if:
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.
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.
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.
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.