How to use your team's most powerful tool: Documentation

Documentation. As a junior engineer, everything about this word tormented me. Read documentation? Ugh, boring. Write documentation? Are you kidding me!?

I believe that this was my biggest mistake as an engineer. At every chance, I jumped right into implementing the code, without even glancing at the documentation. I didn't like documentation, because I didn't know how to use it.

Documentation is many things. Most importantly though, it is a starting point for in-depth conversations. In this week's blog article, we'll be talking about how any team member -- new and experienced alike -- can use documentation to do great work.

1. Use documentation to deepen your understanding of the team

In an earlier article, we explain why it's important to understand your entire team's work, even if parts of it don't relate to your own. This understanding can be used to generate new ideas, to help others, and to be a better team player.

Documentation can help a lot in developing this understanding. Once you have explored the documents, broadening what you've read should be your next move. Here's an example checklist on how you can get started on that.

1. Schedule 1:1 meetings with teammates to learn more about their work

2. Before having these meetings, ask about any related documents

3. Read through any related documents beforehand, and make notes on what they're about. Create an agenda, and a list for questions, like the one shown here.

4. Go over these notes in your 1:1 meeting, and fill in any gaps that may exist.

Not only will you have valuable context for your meeting beforehand, but you will also help in editing those docs, by pointing out the places that don't make sense.

2. Reflect to create a broader understanding of your work

How does everyone's work converge? Does the current workflow support everyone? How does my work relate to the big picture? Your team's documentation is a great starting point to begin answering these questions.

Start by placing the docs for each project side-by-side. Then, read through each project, and focus on the high-level ideas inside. The link that connects these projects can be found when you start looking at things in the big picture, and laying out documents like this helps you see things at that level of abstraction.

For instance, in one of my past software development teams, I built a tool, and I wondered about the tool's use case in another project. I read that project's documentation as described in this post, and pinpointed it's high level use-case. From there, I pointed out exactly where my tool would fit in, and had a chat with the other members, which led to some really useful insights gained from a tool that otherwise would never have been used for any additional projects.

3. Innovate, by reading outside of your team

What are the differences between the marketing team and the data-science team? What about the similarities? These teams work and think differently. Yet, they still converge at some level in pursuit of a unified goal.

Reading documentation is an excellent way for you to see what different departments are up to, and how they interact. It can also be a great way for you to gain new ideas. Another team may have solved a similar problem that you are currently working on. Or perhaps their way of thinking can offer new insights in your team's workflow.

As we've mentioned above, though, documentation is a starting point for in-depth conversations. So use a team's documentation as an introduction for reaching out, just like in point 1. "Hey, I read about ____ in your team's documentation, would you mind talking with me a bit more about it?".

4. Do great work, by creating great documentation

I know what you're thinking. "Sid, have you SEEN what my team has written down? I don't know what to call it, but it ain't documentation!".

OK, I've explained how you can use good documentation to empower your team. But what if your documentation is disorganized, or perhaps non-existent?

Fixing bad documentation is a great way to make a huge contribution, as well as learn a lot about the context of your work. In addition, there are a lot of benefits to encouraging your team to write better documents. By striving for great documentation, you create structure in your work, that enables you to narrow in on the details. "Are my ideas simple and easy to communicate? How do they relate with other ideas that are going on in the team, or perhaps company?".

Additionally, keeping bad documentation around can lead to extensive (and expensive!) technical debt. I've personally been in the situation where I’ve needed to learn how something works, and going to the docs actually made me more confused. I've also been in the situation as a newcomer, where the documents aren't friendly to read, and make me feel even more disconnected from the team.

Conclusion

All in all, we believe that documentation is a great starting point for meaningful, in-depth conversations. It's a tool with a lot of potential, and can be used to strengthen the understanding of your work, and of your team. It's also a great way to gain insight from the ideas of other teams, and begin communicating with them.

Even if your team (or company) doesn't have good documentation, it's an excellent initiative to encourage its development. Writing documentation can bring structure to your team's work, and help your teammates think about both the small details, and the big picture.

That's it for this week's blog article, thanks for tuning in!