How to organize the engineering team's documentation?

Short Apr 13, 2021

Every engineering team has some sort of documentation of their team's work. Most often, these documents get disorganized reasonably quickly. People have a hard time finding their way around. When adding new records becomes painful, people start adding them into the wrong places. There are some tricks to solve the problem.

Three Click Rule and Simplicity

Making things simple is the power of Apple's success. They removed every friction as long as they can to achieve simplicity. Reaching the simplest approach requires hard work. As Steve Jobs said:

"Simple can be harder than complex: You have to work hard to get your thinking clean to make it simple. But it's worth it in the end because once you get there, you can move mountains."

This simplicity led to the success of the iPod. Steve Jobs forced the design team to provide access to any song or functionality in only three clicks.

The documentation's goal is to record the work and make accessing and finding simple. That's why using the three-click rule to access any document is one of the most excellent strategies.

How to achieve simplicity in documentation?

Most often, people confuse two different things. With documentation, the goal is not to keep records; it is to make the information accessible, preferably with less than three clicks. Writing the document itself is keeping a record. Placing it is archiving, making it accessible, and it requires a different mindset.

To get into this mindset, put yourself into a member of another team. How would you find information as an engineer? What are the essential things you care about? Where would you look for a specific piece of information if you are a product manager? Take a look at the product, engineering, and other perspectives separately. Understanding multiple sides is as important as the document itself.

The documentation is not only for the team but also for the people from outside. When they reach the home page, they should find what they are looking for quickly. Make the home page for other people, not for you. Don't put information, instead use it as a link hub and provide links to important pages.

Split product, engineering, and team routines into different buckets. Provide product managers their own place and delegate the document organization to them. Use the engineering section for technical documentation. Separate team routines from the technical documentation. What are the things you do regularly? Place them under the routines. For example, onboarding, the definition of done, the definition of ready, meeting notes, vacations, etc., fall into this category.

In the end, the documentation and how you organize your documentation space will shape your relationship with the stakeholders and other people in the organization. The relationships demand constant effort and optimism. If you don't care about your documentation, you will receive a lot of requests and complaints.

Candost Dagdeviren

Sr. Software Engineer. Writes about software engineering, leadership, tech, cultural differences, and their effect on people.

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.