In part one of this topic, Empathy, Meet Documentation, we talked about why a company environment can make it challenging for teams to write documentation. When folks compete with each other rather than working as a team, documentation can be intimidating. When everyone is racing towards the deadline, documentation often comes last or not at all.
If you are reading this, documentation may already be a part of your process—yay! At Sparkbox, we believe empathetic documentation is not just a checkbox, but something that truly contributes to the long-term success of a project and team. So, how do you accomplish these empathetic big ideas? Let’s discuss some practical guidelines for writing documentation that provides the most value for your team.
The Nine Tips for Writing Empathetic Documentation
1. Keep Documentation in One Place Whenever Possible
Spreading documentation across multiple platforms is not beneficial and discourages people from using documentation—which defeats the whole purpose of having it! Try to limit your project’s documentation to one platform to eliminate complexity, rewriting, or duplicating documentation.
There is a case for having multiple platforms, such as having both public and private documentation or separate instructions for non-developers who need to offer suggestions to a codebase. If this is the right option for your organization, do not copy documentation over. Instead, we advise you to link between the platforms to create a single source of truth.
Whatever the solution, create an index to make documentation easy to find. Having a list of links with a rationale of what they include makes it easy for all team members to find and add new documentation. Like any other kind of documentation, this index should also account for location or rationale changes. If your index becomes lengthy, consider using a platform that has search capabilities.
2. Write Documentation for an Entry-Level Employee
A priority of empathetic documentation is writing for the new person on the project or the entry-level employee. Don’t leave something out of the documentation because it feels too obvious. That doesn’t mean that you have to write for someone who has no technical experience, just keep in mind that your team members may not have as much exposure to the specific details you have. Having clear and understandable documentation levels up everyone’s knowledge and helps avoid errors and dependencies on specific individuals.
3. Find the Happy Middle Between Too Much Information and Too Little Information
Code challenges are notorious for making developers dig in and learn new things on their own, but someone using documentation shouldn’t have to prove they are a great problem-solver. Giving users too little information can leave little time for critical thinking about the actual problem—working on the project!
On the other hand, you also don’t want to turn your documentation into a food blog and make readers wade through a long backstory when all they need is a chocolate chip cookie recipe! Writing too much forces users to weed through documentation to find the information that is important to them.
4. Try to Keep One Action Per Step
When writing out steps in a process, be concise. The goal is to take necessary actions as scannable and hard to miss as possible (much like website usability!) If a single action has several steps, try breaking each action down into a sub-point. If you have over three subpoints, consider creating a new section or a subsection with those points as regular steps.
Remember those hard-to-follow multi-part math problems from high school that should’ve been formatted as individual questions? Use these as your inspiration for what to avoid.
If you have problems remembering the steps you took as you are writing the documentation, here are two tips to backtrack your thought process:
Scaffold Documentation as You Go
As you are starting to get things to work, quickly write some documentation as an outline that only you understand. Revise it once you have figured out the process and submit it for others to review.
Review Your Terminal
If you are a developer trying to remember all the commands you used to get an environment running, a project updated, etc., the history (Mac/Linux) command or F7 key (Windows) is your friend. This shows all of your previous commands regardless of having run clear or closing out your terminal. This allows you to look through your process and remember exactly what you ran in chronological order.
5. Provide the Expected Outcome for Each Documentation Step
When you’re following development documentation, you are often met with a list of steps leading to an objective: setting up a local environment, updating dependencies, etc. It is the developer’s job to follow these steps and troubleshoot anything that goes amiss during the process. However, troubleshooting can often become time-consuming because the step never explains your goal. Let’s look at a common scenario when setting up your own local environment on a new project:
You open the documentation, and line one says:
Run npm start.
Now what?
Say you are met with an error. What things are trying to run? Sure, you could begin to try and figure out what is going on, but wouldn’t it be nice to see this instead:
Run npm start to compile/watch the styles and start up the Docker container.
This is not a full breakdown of npm, docker, Sass compiling, or how the package.json file was set up. It just alerts the reader to how the tools should behave at this particular step on this particular project.
Even though npm start is a common command for starting up development environments, this alone doesn’t summarize the expected behavior on each unique project. Giving the developer success criteria for each step allows them to know if it worked successfully and confidently move on to the next step.
6. Give Examples If the Rationale Is Complicated
Sometimes, providing success criteria in a step doesn’t give enough context for the project and can feel more cryptic than helpful. It’s best to provide examples to make these tedious tasks easy to understand.
For example, if you are documenting a very specific use case for a UI element you may end up with a point like this:
The sugar-cane section should only live after the closing tag for <div class=”candy-dish”> and the opening tag for <div class=”willy-wonka”> because it was made to border those two elements.
You get the idea, but you would likely have to re-read it several times and pull up the code and figure it out carefully. Adding a shortened example as a sub-point illustrates the above statement done correctly:
<div class=”candy-dish”>
<!--content-->
</div>
<!-- Place sugar-cane here -->
<div class=”sugar-cane”>
<!--content-->
</div>
<!-- End sugar-cane -->
<div class=”willy-wonka”>
<!--content-->
</div>
Pairing rationale with a snippet of the environment allows the reader to see the point of the information and the proper execution of the idea. These two things offer greater confidence that the implementation is correct and reduces the need to reread the step and search the project for answers.
7. Let Someone Know When and How to Reach Out for Help
When a developer needs certain access rights, write it in as a step. This is a step that is very easy to overlook because you and your teammates may have had access to a certain password database or user group for years. This could look something like:
“Use the password in X location to access the database. If you do not see this location, reach out to your director or a project manager to get access.”
There also might be some cases where there is no way to get around needing a certain level of expertise on a specific part of the project. Learning something new puts people in a vulnerable position where they may need additional help to get moving. Encouraging others to reach out for help is a great way to get people unstuck and encourage shared learning.
8. Keep Your Documentation up to Date
It’s easy to become cynical about this point. “Yeah, it’s just soooo simple! Just keep it up to date!” This is the most difficult part of documentation. It requires the most individual diligence and team cooperation—which also requires a lot of trust.
Reality check: it is impossible to keep your documentation 100% up to date all the time. However, you should have a process in place to review and update documentation regularly as you are making changes. Here are some ways to build this into your team:
Ask newly hired employees to help. They’ll be heavily relying on the documentation, so encourage them to point out things they don’t understand so the team can work on enhancing or clarifying the documentation.
Periodically use the documentation for a familiar task. As you go through the task, you may be surprised at how many errors you find in the documentation. Since you know the steps in your head and the outcome you want, it likely will not take long to open the documentation and see if it lines up.
Add timestamps to your documentation. This allows folks to know which pieces of documentation are up to date and which ones haven’t been touched in a long time.
Check existing documentation as you make modifications. If you are modifying a functionality, check if there is existing documentation and if it needs to be updated. And as I stated earlier, be sure to include it in your review process so users can view it alongside the changes.
9. Create Good Practices Now to Get Out of Your Documentation Debt
Maybe you already have what seems like an unrecoverable amount of tech debt in your documentation. This can be the main reason for avoiding documentation in the present and the future. However, ignoring it only adds more debt. Even if you don’t have time to fix the debt all at once, you can positively affect the future and current projects.
Clearly communicate a new process for documenting to your team. Eventually, the old documentation will be replaced as people work on those projects again. When suggesting edits to another person’s documentation, remember that you may not fully understand the project’s history or the different approaches someone may have used previously. If the person is still at your organization, ask them about it! Remember, it’s not about being right, it’s about learning from each other.
A Helpful Pattern We Follow
For our company-wide best practices and technical onboarding, we have The Standard as a GitHub repo. This allows folks to contribute with a built-in review process as well as keep track of previous versions and contributors. We encourage our new hires to contribute to The Standard within their first month.
For our projects, we include a README file that has the following:
A brief summary of the project
A list of primary contributors
A list of technical dependencies
A table of content that links to specific files in a
docsfolder or a link to the project wiki
A docs folder or a project’s wiki is helpful for several reasons:
It is easier to navigate than one long README file.
Each developer on the project can document what they are working on as they go without having to worry about merging conflicts in one file.
It’s easier to review pull requests when the documentation file coincides with the code that is being reviewed.
Since this is our general format, we make documentation a built-in part of reviewing pull requests. This helps us make sure that the documentation for the feature or process exists and that it makes sense to at least one other person that didn’t write it.
Go Forth and Document
Hopefully, these perspectives will inspire you and your team to have a conversation about documentation, create new ways of organizing it, and allow greater understanding between teammates.
Keeping an open mind and empathy at the forefront of documentation discussions is important since it can bring up a lot of history for many folks involved. Learn and adapt to each other’s needs. Cheer each other on and work together.
If you’d like another set of eyes around your documentation processes, we’d love to work with you. Contact us and we’ll be sure to get in touch.
