One guide of how to document the team tech decisions
Stop using lack of time as your excuse and achieve great documentation in your teams
This article was written collaboratively with Pamela Peixinho
Lack of documentation is a huge and old problem in software development. We all know that. We have already complained about the lack of documentation during a software discovery as we also haven’t written documentation of software that we built. Maybe you also asked yourself “what have I done here?” when looking at old software that you have worked on.
At QuintoAndar this problem isn’t different. We have a bunch of products, services, flows at the same time that we also have a bunch of people working on them, impacting the same users. So, how can we stay sane in this situation and make sure we're exchanging knowledge?
We have already made a great improvement in adopting the Architectural Decision Record (ADR) concept. We are now creating documentations about our architecture decisions, which is amazing and helps us to get everyone on the same page. But what about our flows, APIs, components, and team decisions during development?
Looking at these problems, we can say, and we have already heard: “Our code and tests are our live documentation”. This sentence is completely true! That’s why we should take so much care to build high-quality code. On the other hand, this is not enough.
We need to know the background, decisions made, and their rationale. Our codebase just shows us a picture of WHAT is running in the software, not WHY, and HOW it was achieved.
Having all these “not coded” content makes us effective and helps avoid rework in your team during development and help others’ team discoveries. So, with this in mind, we can split the documentation usage in these two moments to get the most of it in each phase: before/during development and after the development.
Before and during development documentation is an important tool of communication and alignment to put all team members on the same page. For example, you and your team may have discussed the feature, decided the data modeling (database and API), but one developer is doing the endpoint and another one is creating the data request to show data in the front-end, how can we make sure that both are looking to the same decision and can work simultaneously? How can we make sure that the person that will test the release will also know the most recent team decision?
Creating documentation that records team decisions about what it is currently developing is a simple and easy way to have a great communication tool between all team members even when one of them is not present. So, all of them know the contracts between the endpoints and the front-end because we are always updating the same slice of info in the same document. These updates should be everyone’s responsibility during the team process and a good result is to have great software along with all decisions and descriptions.
After development, the documentation built gains another ton of importance. Now, this document helps us to communicate with the ones that weren’t present or that already forgot. We are creating a tool for our future selves. For example, we need to create a new feature in one of our services using another feature already built by another team. In order to do that, we need to understand:
- how it was built
- what service was involved
- what decisions were made in order to create an accurate flow
- what was the rationale for it
- what use cases of this development covers
- how to test it
When you’ve already created unique documentation that contemplates all of it and has links to the other related stuff, it’s really faster to start a new development.
It is like time traveling to communicate with the team during the development ⏳
Therefore, we can see that communication is a key point to enhance our software development in a scalable and easy to maintain way. As Martin Fowler said in one of his articles:
Why do we bother with models or documentation? They don’t execute, and our customers pay us for working code, not pretty pictures. We bother with models to communicate.
Accordingly, to previous points we can understand the importance of creating documentation, but how can I create documentation that will really be effectively used and do not cost much? How do we avoid over-documentation things that will create more doubts than solutions? Looking to this point we have created the Engineering Doc concept using the Design Doc concept as reference.
Documenting Tech Decisions
In order to centralize all engineering related information of the product development, we have used an engineering doc template to record the team's tech decisions. This template could contain, but not limited to the following topics:
- Introduction
- Product goals/Key results
- Engineering
- UX
- Data engineering
Those topics could help the squad to insert decisions and to document what the team has done while creating new products.
To achieve great results recording decisions, the template doc must be created and maintained by all the people in the squad (from business person to engineering). One thing in common in the document is that it needs to be available and understandable independently of the person’s skills.
In the engineering section, we need to be careful to document tech decisions that do not overlap with automated documentation of software. For example, while developing new APIs we have tools to document technically and automatically endpoints using Swagger. If your service does not have it, use the document as a workaround. So, the engineering doc should be used to centralize all the decisions related to WHY and HOW the product was built in that way.
When developing software in a fast-paced environment, we’ve found that it’s very common to forget important things for example tracking and monitoring. So, the template will guide teams while developing new products, setting anchor points of what matters for your organization. Revisiting this document during all software construction (idealization, coding, delivery, production metrics, etc.) is a good starting point to have up to date and consistent content.
When should our team start a new engineering doc?
Prior to developing a new feature, the project owner (engineer or business person) will probably start a new discovery to understand what we have so far before starting developing. This initial discovery will have information about a microservice, business rule, or a completely new system design. This is the perfect scenario to start the document placing all related information and sharing it with your team.
While the new things are coming the team could fill the sections in order to register all events and decisions linking the official documentation for the respective sections. This process was described in the image Flow to illustrating the documentation process above.
Over-documentation
Therefore, should I write everything in this document?
Not exactly. Take care! Worse than not having documentation, is having documentation that nobody will read because it is so over-documented. We need to find the right balance of information. So, always ask yourself if you’re registering important decisions that it’s really necessary for the development and later consultation or just writing buzzwords about your development.
Outdated Documentation
So, every time I change something related about this document should I update this doc
NO! This is not the live documentation. It’s live documentation ONLY during the development process, but after the development, it turns into a “register”, a static document of the team decisions. Imagine that every time we make a decision, we register the decision, we have all logs of the different teams linking each other.
Behind the scenes
We focused before in documentation as a communication tool, and we want to step back to explain how was our process to achieve it.
In our team, we were recreating an architecture, and we needed to work at the same time in different services using the same data structure even when it wasn’t there yet.
Our first problem was no documentation at all, obviously a problem. So, we started creating one document to explain the architecture, another one for the testing scenarios, another that contained the data structure, creating what we called documentation hell 🔥.
Then, we didn’t know where to find anything, and at the same time that we had sure that we documented it. So, the creation of the engineering doc linking the design and product doc explain all about development turned all as documentation heaven 🎉.
So, stop using lack of time as your excuse and achieve great documentation in your teams. Just try adding this in your process this template or create your own in order to log the decisions while it's happening. You will see the results! Do you accept this challenge?
If you’d like to be a part of and help shape awesome processes like the ones described here, join us!
