Document Culture
Hello!
I hope you had a wonderful weekend! We're celebrating here because the 49ers are playing at the Super Bowl.
Was this forwarded to you? You can subscribe here!
Have you ever had a string of meetings where the presenter has to re-introduce the context, but prior attendees had understood something different? Or worse, every session has to be started from scratch because no one remembers the context, and new people show up.
Have you ever noticed that the tenured people remember why something was done a certain way? This makes it hard to review decisions or sunset them in favor of something that matches the current context.
Documentation and reading culture are at the core of solid engineering cultures. Running effective meetings and bringing people up to speed, with people being able to string the story and decisions that allowed for something to happen, is a game changer.
Stabilize Ideas
Written documentation allows us to stabilize ideas as they occur. People can bring their context and ideas, but what gets written will be a collaborative effort between those participating in the project.
Having a document will help with scope creep when new people show up to ongoing projects and ask, "Why didn't we do X?" and that is documented with its trade-offs.
Shared Understanding
One of the famous examples of document culture is Amazon. They go to great extents, meaning it will only get done if it's on a document.
An aspect that I liked from reading about that was that they reserved time at the beginning of meetings to read the presented document. This helps attendees have fresh context and with subject matter experts (SMEs) present in the room to answer questions and fill in gaps.
But the other aspect that comes into play with these types of meetings is the shared understanding in a given timeframe gets written from the conversation, the shared context by all attendees.
Async communications
When you have a document to materialize context and project status, you can start receiving comments from readers in an asynchronous manner.
This is a great equalizer when working with remote teammates and when teams are distributed globally! I've worked with teams in 3 timezones.
Let me know your stories about more time zones!
Send information to the future!
One of the benefits of documents, which has served the most, is being able to "send information into the future." What this implies, for me, is the ability to reach back to documents that detail why we did a specific thing or why we chose technology over others at a given time.
This has been useful for me when teammates ask: "Why didn't we choose Kafka at that time?" Or "Why did that project choose to extend this service instead of creating a new one?"
In one of the cases, past decisions no longer fit with the current context and had to be revisited to upgrade the solution.
We can go back and review the trade-offs at that moment in time.
Conclusion
Building a solid document culture will help your organization in the long run. It isn't easy to start it if your team is used to setting up meetings for everything!
One of the things that you can do is run Bite Size Architecture Sessions or start by creating solution design documents for projects.
Let me know your thoughts on how your company deals with documents.
Happy coding!
Things I found interesting this week
- The Power of Being New talks about how being new provides an opportunity to fix problems that others have overlooked.
- Inside .git, as usual, Julia Evans with an insightful comic about the inner workings of git!
website | twitter | github | linkedin | mastodon | among others