Effective Documentation for Teams

Introduction

Documentation is hugely important. They say that a company’s most valuable asset is the knowledge inside its employees’ heads, so why not get that info out of their heads and into a place that everyone can access?

I’ve been documenting things for myself and my team for over five years. I document systems, bugs, processes, troubleshooting, outages, and much more. It has saved me many, many, more hours than it has cost me. Just like any other part of your professional life, you want to do it to the best of your ability. It will make your life easier, help your team succeed, and show that you’re a star performer.

This article is written with the software engineering field in mind, but the information is applicable to any industry.

The Problem

Documentation is commonly skipped or half-assed. I often hear the excuse, “I don’t have enough time to write documentation!”. The reality is that over the long term, your documentation will save you time. Overall, your job will be much better if you have documentation.

There are questions that people often have that prevents them from starting their documentation journey, including:
Where will I put the documentation? How can I make time to write documentation? What should I document? Can I put it in too many places? How can I make sure people understand my writing? What does documentation even mean? How do I know anyone will ever see what I write?  What counts as “documentation”? Will I lose job security? How do I organize it? How can I encourage my team to contribute to documentation?

Where do I put my documentation?

Put it somewhere that is easy to access and easy to search. SharePoint is ok. A shared OneNote is better. Confluence is best, in my opinion. My teams use Jira. With Jira you also get Confluence. Most of our engineers are always logged into Jira and thus always logged into Confluence, reducing the hurdle of having to log into yet another system. This increases the amount of documentation your team produces and consumes.

Make a space in Confluence or a shared OneNote and start throwing things in there. Worry about organization later. Do not let perfect be the enemy of done. Keep your documentation limited to one place if you can. Don’t have a Confluence and a Sharepoint and a OneNote and a private Stack Overflow.

I also keep a personal OneNote and document a lot of things for myself. If I feel that those things would be useful to other people, I share them in Confluence.

How can I make time to write documentation?

Documentation is an effort multiplier. You may spend an hour to write documentation, and it will save you many hours over time. I cannot count the number of times that someone has asked me a question about some obscure process, and instead of meeting with them for 30 minutes I can just send them a link to a page on Confluence. This is especially helpful because it’s hard for me to get time to have a spontaneous 30 minute technical conversation without interruption, but if 80% of the knowledge they need is just one click away, I can send that link and carry on to my other tasks. Plus, they can easily share it with others.

You don’t really want to type out the same “gotchas” for connecting to that third-party API over and over, do you? It’s better to just send a link with all that info. There are so many times when it has taken me hours to figure something out that could have been solved in five minutes if there was documentation for it. Those are the things you should write down.

What do I document?

Any time you’ve wondered how a process works, you could document that. If you have had questions about it, there is a very high chance that others have questions about it too. And even if they don’t, you will forget this process eventually and probably have to revisit it and relearn everything.

Or, the first time you encounter an issue you could think to yourself, “This was pretty confusing, but if I knew at the start what I know now, I would have been able to solve this issue quickly.” Then you can write that information down. There are so many times where this happens, and yet people just think “yay I solved the issue :)” and move on to the next issue. If you don’t want to keep solving the same issue over and over, you should document as much as you can.

You can document a specific process with a third party API. You can document columns in the database and what depends on them. You can document your git strategy, your scrum strategy, or your process for pushing code to production. Document all the web pages that new developers should bookmark. Document how to get some code to build after pulling down a repository for the first time. Document your scrum retrospective.

You can, and should, also document events such as outages. Document what broke, when it started breaking, when it was resolved, and what fixed it. You should also document the root cause, and try to get as close to the real root cause as possible.

There is no such thing as over documenting. Documentation will help out your team, and it will help out other teams such as your customer support team and product team, and it will help you out as well. The life you save may be your own.

How can I make sure people understand my writing?

The people who are the best candidates to write documentation are the people who like to write. However, I do not want to discourage anyone from writing documentation. If you have something you think is worth documenting but you aren’t confidence in your writing, just write down what you can. It doesn’t have to be poetry, you can just write bullet points.

Even if you are documenting in a language that is not your first language, people will understand what you mean. They may fix grammar errors themselves, or you can also ask coworkers to review it. Some documentation is better than no documentation! Write away, right away!

What if I write it and no one ever looks for it?
Documentation can be a vicious cycle: People don’t write documentation because no one thinks to look for it, and no one thinks to look for it because no one writes it. You have to break the cycle by writing documentation. I suppose you could break it by looking for it and then complaining loudly to your team when you come up empty, and hope someone else writes it, but I haven’t tried that method yet.

If you write it, they will come. If you think something is worth documenting, there is a very good chance that other people will find it worth reading. That person may very well be the future you. If you got confused about something one time, there is a good chance you’ll have questions about it again.

Even in the worst case scenario, where you document something and no one ever searches for it, it is still worth it to document. Why? Because the process of writing something down will make you remember it. It will also make you realize where you have gaps in your knowledge, and then research to fill those gaps.

What does documentation even mean?

Documentation is anything that you or someone else may need to know. We often forget how much we know. There is a ton of information inside of us that would be lost forever if we left the company or got hit by a bus. These things are documented in our heads, but they could be documented somewhere that is stored in a safe place, accessible by other people.

Documentation can be at the team level or the personal level. I write notes in my OneNote every day. I break it out into notes for each day and also areas where I write notes for various systems, teams, or tasks. Each day if I want to know what I worked on, I just flip to the notes of that day. If I ever leave my job or get let go, I can just share my OneNote with my team and now they have a (slightly chaotic) searchable record of everything I worked on during my employment including the “gotchas” I ran into and how I fixed them.

Will I lose job security?

No, but you will gain the ability to be promoted. No one is a golden cow. No one knows information that is absolutely impossible to be learned by someone else. Companies fire people even when they are afraid to lose them, so don’t think that hoarding information will save your butt. Documenting something is not going to be the thing that tips the scales against you. Be a team player!

Think about it like this: Who is a more valuable person to the company?

• Employee A: Knows a lot and keeps it to themselves. Anytime there’s an issue with something they are an expert on, you have to set up a meeting with them to get the information out of their head. You have to keep going back to them with more questions. It’s a slow process.
• Employee B: Knows a lot and puts it in a place where other employees can access it. When you need to know something about their system, they say: “I’m in a meeting right now but here is a link to how this process works. Let me know what questions you have and we can catch up later!”. Eventually the entire team learns that searching the documentation is easy and likely to solve their issues in a short amount of time.

How do I organize it?

I recommend Confluence for most documentation. It is easy to add pages, easy to edit, easy to search, and easy to share with others. They have useful templates including for how-to articles, sprint retrospectives, and dozens of other things. You can break things into sections however you want; we prefer to do it per team and per product. You should also make use of the labels such as “kb-how-to-article” and “kb-troubleshooting-article” to help you find articles super fast.

The most important thing is to get the information down somewhere. Once that’s done, worry about organizing it. Don’t let organization get in the way of documentation.

How can I encourage my team to contribute to documentation?

Documentation is a vicious cycle. The best way to break the cycle is to just start documenting. Eventually you will be linking people to documentation you wrote, instead of typing out how different processes work over and over and over.

Usually the hardest part is starting a new document. Once the document exists, it’s easy for people to contribute pieces of information to it.

Here are some ideas for encouraging it:

• If you do scrum, bring up in sprint retrospectives that the documentation could be improved.
• Mention it in stand-up meetings and other team meetings. E.g. “yesterday I documented the process for how to make accounts for dogs…”
• Add requirements to tasks that requires the employee to add information about that process to Confluence.
• Create an OKR about creating documentation.
• Give candy and snacks to those who document. Good ol’ classical conditioning!

Conclusion

Creating documentation is rewarding and a great use of time. So many employees complain about a lack of documentation, yet never think to create it. Documentation is a keystone habit that is very powerful once the habit is established. It causes developers and other employees to come to a deep understand of their systems. It decreases the time required to troubleshoot bugs. It makes people think about their processes in-depth and develop process that are clear. It prevents knowledge loss from your subject matter experts. It saves you time.

Start writing documentation today! Even if it’s not perfect, just get your thoughts written down and add to it little by little. Soon, you and your team members will have an impressive garden of knowledge.