Documentation is hard, especially if it’s for your own internal purposes.
It can seem overwhelming and impossible to fit into an already busy environment.
It can be hard for teams to adopt because the negatives can seem to outweigh the positives.
It may cause negative reactions from your team due to past experiences.
It may seem too expensive since your team would need to spend a lot of time on it, and the budget is already tight.
It can be hard for teams to embrace an empathetic mindset when writing documentation.
Ah, “empathy.” Oh, no. Is this yet another article that overuses the industry’s favorite buzzword to explain a topic it doesn’t apply to? I’d argue not. Empathy is only weakened when you misuse the term to talk about something that isn’t actually “empathy.”
So, we’d better define it. The Nielsen Norman Group defines empathy as, “...the ability to fully understand, mirror, and then share another person’s expressions, needs, and motivations.” Later in the article, they mention that empathy enables us to “… improve our users’ lives by removing unnecessary pain or friction.”
Now wouldn’t we like to “remove unnecessary pain” from using and writing documentation? Let’s introduce our dear friend Empathy to our perhaps long-lost friend, Documentation.
Documentation vs. Anti-Documentation Culture
Pride and stress often lead to poor documentation, whereas humility and empathy allow for a collaborative and respectful space to write useful documentation. When the culture is ego-driven, it’s difficult to ask clarifying questions without fear of looking unintelligent or feeling like you have to compete with your team members to keep your position.
When stress drives culture, the goal is to get to the finish line as quickly as possible and stay within the budget at all costs, without allowing time or thoughts for improving the process. So, if you are afraid of looking unintelligent or constantly pushed for time, it makes sense that your documentation is a bit cryptic. People will unnecessarily use fancy words or jargon so that they either look like they know what they are talking about or just push something out that only makes sense to the person who wrote it. Let’s ask a couple of questions that let us evaluate the environment:
When you are unsure of how to do something, are you intimidated to ask a teammate or manager questions?
When you read documentation, don’t understand it, and ask clarifying questions, do others make you feel incompetent with their responses?
Do you feel like you have to earn the right of passage to “senior-level knowledge?”
Do you feel like if you gave out your knowledge freely, you would risk your position to someone below who could do it just as well—and for less?
Would you like to write documentation but feel like that can only happen in an ideal situation because projects need to get done as soon as possible?
Do you feel like you are bothering the same person over and over again because they are the only one that has knowledge about a certain project?
If you found yourself saying “yes” to any of these questions, I think we can start to get on the same page. While it’s not immediately obvious, a great way to understand where your people are at is to look at the state of your company’s documentation.
Now that we’ve looked at behavioral contributing factors, we can evaluate the documentation through a similar lens. Here are some questions that can start to give you a good idea of where the documentation is at:
Do you have documentation or do you rely on individuals to be the keepers of information?
Do you know that your documentation is outdated but you just haven’t had the time to update it?
Does your documentation feel so obsolete that it seems impossible to fix?
Are colleagues (not just management) able to easily suggest edits or update the documentation?
While these questions are more subtle, they give you a glimpse into whether folks feel like a trusted and valued individual or just a replaceable cog in a machine. Unfortunately, some may feel the ego-driven culture is just “the price of doing business,” but what would it look like if a team put empathy first?
Empathetic Teams Lead to Empathetic Documentation
Empathetic teams support each other rather than compete for control and status. Clarifying questions, suggestions, and new ideas are welcomed rather than silenced. People can confidently share their knowledge without fearing that they’ll lose their job once others learn it. Folks know they have the time to write the documentation on projects and suggest ways to improve because the scoped deadline and project cost includes a margin for human error and documentation for future success. Shifts like this make documentation a good barometer for the company culture.
Sparkbox VP Rob Harr co-hosted a conversation with Traci Barrett about the power of empathetic teams in contrast to internally competitive teams on their podcast, “Overly Human: Think Win-Win: The 7 Habits of Highly Effective People.” I would highly recommend listening to this for more insights on how empathy changes internal and external interactions and streamlines Rob and Traci’s processes from a leadership perspective. If you find it difficult to picture the differences between an empathetic and ego-driven environment, both hosts do an excellent job of painting what each picture looks like and why empathetic teams are more effective.
The Case for Empathy-Based Documentation
Empathy and documentation can make or break an employee’s experience in a company and are critical for making everyone feel confident enough to contribute to the team.
I recently did a short talk on empathy-based documentation for a community-based development organization, and I was amazed to see that everyone in the room had a personal bad experience with documentation. I heard comments like, “They made me feel inferior when I asked a question.” or “They didn’t want me to compete for their position, so they wouldn’t tell me what to do.” or “The developers thought that if we just wrote clean enough code, we wouldn’t need documentation and now we have a legacy codebase.” or “It was so outdated that no one wanted to even touch it.”
Many folks in the tech industry probably have a story about documentation or asking for help. Documentation seems like it only happens in an ideal world. For those who wish to make improvements in their own organization, it can be hard to even know where to begin the conversation. Figuring out how to discuss documentation can open up more conversations about empathy and humility in general.
Sometimes documentation is hard to start because the common pitfalls can seem to outweigh what feels like imaginary positives (i.e., abstract ideas and non-concrete results). But recognizing how documentation can benefit you can help you have more productive conversations with others about how it benefits them. Here are some advantages of documentation:
1. It can be your personal assistant—Take a vacation
You don’t have to keep track of everything or remember exactly what you did on a project. You can write it down and forget about it until you need to remember it again! Documentation also allows you to mentor others when you aren’t around. Ever wish you could be in two places at once? Now you can!
2. It strengthens your own understanding of the project
Did you know that teaching a topic increases your expertise in it? Don’t avoid writing documentation just because you don’t fully understand what you did. If you just endured a drawn-out, painful process, we understand how tempting it is to throw in the towel. We advise you to get up, take a break, and then document it. Why? Writing a concise set of instructions will help you complete future work for this project faster and serve as a quick guide for newcomers. The last thing you want is to relieve that aggravation because you forget the process or subject someone else to the same pain you went through. Show yourself and your teammates some love!
3. It reveals holes in your internal processes and increases your efficiency
You don’t have to solve all of the problems in your project in order to document it. Don’t let your perfectionism feed you lies like, “ugh, that one part isn’t fully fledged out so I can’t really document it.” It is very helpful to call out the unknown so that another team member isn’t left to wonder if that area of the project has been considered. On the flip side, don’t pretend you have the answer in documentation if you don’t! This will not help anyone find the correct answer faster. It’s better to call out the hole and move on.
4. It adds ongoing value to your team’s work
What if documentation wasn’t a side-project? What if it was valuable enough to charge for? Would you rather charge the client or yourself once for a well-written manual about the project or bill for countless hours of refactoring code because your team is no longer sure what it does? Documentation is not a “nice-to-have.” It’s essential to long-term success, and is powerful when paired with an empathetic group of folks who are dedicated to open communication and trust. Your team and your clients will thank you.
All that to say, don’t let perfectionism hold you back. It’s okay to write documentation even if you don’t know everything. In fact, that’s how everyone does it.
Advocating for Good Documentation
If your existing documentation is unhelpful, advocate to fix it. While this may sound obvious, is anyone trying to do this? Maybe you just need to address this issue with the right people. In an empathetic environment, folks will likely be willing to listen and create a plan to work on it.
But what if that’s not where your company culture is right now? Do you have to upend your entire value system to address this issue? Sometimes it is impossible to convince people to abandon a competitive mindset and to adopt an empathetic one. Oftentimes, documentation is not built into a competitive business model because it takes time, and time is money.
If that’s the case, you can start to make progress by framing your process around what is meaningful to the organization. You can run some low-pressure tests to measure how much time people have to take to figure out old projects that have outdated documentation or none at all. Then assign a dollar amount of how much built-in documentation would be worth to the company.
As a developer, it can be easier to track this since you can simply track your own time with something like, “It would have taken me about an hour to write documentation for this and about 15 extra minutes to have another developer review it. Because we don’t have any documentation, it took three developers a total of four hours to solve the issue.”
Whatever area that your company finds the most valuable, start there. Documentation adds value, saves time, and helps people perform their best work.
Conclusion
Documentation is a core part of what companies do and how employees operate day-to-day. It can be challenging to change old habits in yourself and your team, but it is well worth it. Not only is it valuable for business success and efficiency, but it’s also essential for individuals to feel welcome and contribute.
At Sparkbox, we incorporate documentation as a core part of our development and business processes. We believe it is imperative for smooth onboarding and long-term success for our team.
