Stop Wasting Your Own Time & Start Documenting Your Projects
Getting to work on a new web development project is always exciting! But the excitement falls as soon I open the repository and see an empty README with nothing but the project title — if even that. Now instead of diving into building new features and squashing bugs, I'm spending hours trying to get started. I have to take time from other developers to ask why the build won't start, how to integrate with their custom services, where something should go in their code architecture, and so forth. Instead of spending my hours building and testing, I'm forced to wrestle information from multiple people if I can — some who aren't even available anymore and left the company.
Those are the good cases, too. Sometimes the original development team has long gone, there's no documentation, and no one to ask. In instances such as that, hours soar every time an unknown is encountered.
The worst part? All of these problems could have been avoided with the help of proper documentation.
So…What about your team?
Is your development team’s success reproducible? Can developers switch between different projects with ease, or are they defined on one because the learning curve to get onboarded is too high? If it’s the latter, you might have a documentation problem — and it costs time and money.
Sometimes a developer gets “trapped” on a project because they’re the “only one” who knows it. Over time, they may dislike it enough to leave. Now it costs you to recruit a replacement, and for every hour they spend just trying to get started. Good documentation not only lets any new team member get started on a project swiftly, but it also keeps developers from getting “trapped”. Keep your team happy, save time, save money, and let your team focus more energy on reproducing success.
Sound good? Then you’re ready to talk about documentation.
The One or Few Who Know All
In environments where documentation is minimal or nonexistent, it’s fairly common that they have a “Keeper of Knowledge” problem. (Often our previously mentioned “trapped” developer.) The more complex the project gets, the worse the problem gets because the time to onboard a new teammate grows with it. This means there’s one person or a handful of people on the team who know the ins and outs of a project, software, or process and they’re the only ones who know it. If they disappeared tomorrow, the rest of the team would be lost. If you outsource it to a new team, they’d also be lost. Maybe they could flounder through it, but there’s often some crucial steps or nuances that no one knows about, and now they’ll have to be discovered all over again — the hard way.
Why should I write documentation? Who is it for?
Often when explaining why documentation is needed, we use an anecdote about a common developer problem: “You wrote this code ages ago, you’ve come back to it, and now you have no idea how it works or why you made the decisions you did.” (We then all laugh sheepishly since most of us have done this at some point.) While an effective example, it’s also pretty egocentric. The best documentation isn’t written for yourself: it’s for other people.
It’s very possible that someday you’ll outgrow the company or project you’re working on. Would your successor be able to follow the documentation? And what if there’s a new hire or a junior team member joining — would they know what to do, just from the docs? Documentation isn’t a replacement for mentoring, but it can allow you to spend more time mentoring their skills and less on getting set up.
We often say “time is money” and good documentation can save you a lot of both. If people can get a project up and running swiftly, and get to work on what needs to be done quickly, there’s little interruption and “lost time”. On the other hand, without good documentation, you risk them spending hours or even days just to figure out where to start.
Building quality custom software is difficult enough. With good documentation, you can ease the burden of onboarding for new developers. Documentation is for the future. You’re leaving the project in better conditions than when you found it, letting people start off running, and preventing loss of momentum.
If you’re a developer who prefers that egocentric view, here’s a bonus thought: with good documentation, you don’t need to be glued to one project and worry about “what if I leave?” or “will production stop if I go on vacation?” Good documentation gives future you more freedom to have others step in and help anytime.
Why don’t we document?
Most teams agree that documentation of tools, processes, and projects are good. So why don’t we do it all the time?
Moving too quickly or doing too much.
This is one of the most common problems. When teams or individuals are focused only on hitting the next deadline or finishing the next task, they have to cut corners off of best practices. Documentation is often one of the first corners to be cut. They’ll say they can go back and add it later, but when there’s too much to do or never enough time, that “later” often never comes. In this case, your team needs to slow down, do less, and make time. Including documentation in your team's process can help force the team to make the time, but only if hours to do so are considered in time estimates, to begin with.
“I/We know what we’re doing.”
Sometimes people don’t understand why documentation is needed because they’ve been doing something so long it’s “obvious”. There’s a lot of dangerous assumptions underlying this mentality — it assumes they’ll never outgrow the project or company and that the process is “obvious” to everyone. Junior developers are the ones who often suffer most under this problem because they still don’t have enough experience to recognize the so-called “obvious” and have yet to learn the appropriate skills to deduce it efficiently.
“So-and-so will teach them.”
This is often a result of a “keeper of knowledge” problem that self-perpetuates. The person who knows everything about the project is then put in charge of passing on this knowledge to a new team member. As mentioned before, this will be an issue enough if they leave — but your team will also be trapped in a game of telephone. Every time information is passed down, something will be forgotten. The more times you pass it on without writing it all out, the more things we may find ourselves unsure about when we need it.
What makes good documentation? What do I include?
Good documentation: - Provides replicable steps/instructions - Provides guidance on working with the codebase - Provides references to necessary dependencies, services, etc. - Provides reference to the used language and version - Lists any pre-requisite tools, packages, and versions (separate from saved dependencies) - Provides an overview of working environments, their location, and deployment instructions - Is easily understood by individuals of varying skill levels - Provides troubleshooting for common or known issues ("If you see [x] in the console, restart [y].") - If it’s project specific, it goes in the project documentation. If it’s broader, it goes into the company’s documentation of processes and - tools. If it’s broad, but the project will include external developers, put it in the project documentation.
If your code follows best practices, it should be clear to read on its own. In other words, documentation isn’t meant to replace the need for writing good code. Instead, it’s an accompanying guidebook. Think of it as a pocket reference guide that a developer can refer to when getting started or needing help.
Documentation is also not a replacement for onboarding a developer to a project. What good documentation does do is allow conversations to be focused on meaningful discussions and questions.
Not Convinced?
Documentation takes time. Not just to implement into your process, but to maintain and keep current at every step of the way. However, the time to write explanations once is still far less than the time spent if you don't.
If you don't document, you lose:
- Time spent asking other developers for guidance, information, troubleshooting, and any other needed information – which also takes time from the other developers
- Time spent trying to find the right people to ask if they're available.
- Time waiting for answers to unblock developers when they get stuck, impacting the originally projected deadline.
- Time trying to figure out the solution on their own, if possible.
If you don't document, you also risk: - Frustrating your team, both in not having the information they need or having to be the one to constantly give it. - Burning out your team. - Hindering the growth of juniors and new team members because they can't get started. - Hindering work quality because they rushed after being blocked for hours or days to meet the deadline. - Hindering innovation and creativity because there's only time to get it done and not better. - Missing projected deadlines over and over as the same issues continue to be encountered from not having documentation.
But when you DO document, you gain:
- Time to focus on quality
- Time to innovate
- Time to refactor
- Time to mentor others
- Time to QA thoroughly before deadlines
- Happier team members
- A more flexible team
- Peace of mind for the project's future and your team!
The cost of not documentation adds up fast, and it will cost more and more as time as go. Not only do you avoid those time sinks and loss by documenting, but you gain more time for your team to do what they do best. Effective documentation shares a lot of benefits also found in human-centered design when created with empathy, which allows your team to stay on the page when a decision is made to pivot or persevere.
Documentation is a crucial part of any recipe for success.
We want to document. Now what?
Excellent! The first thing you should do is ensure everyone knows it’s a priority and non-negotiable. Let people carve out time in schedules to document old projects, and make documentation part of the process. Your team can’t just say it; they need to walk the walk. However, they also can’t do that if not giving resources to do so. If management is giving them too many short deadlines, they won’t have the time, and the cycle will continue.
If you’re in a management position, discuss with your team how much time they would need. Are this week’s tasks too many? What can wait a while longer, so we do have time to document our projects? Then embed documentation as a step in your company process. A checklist on a pull request or kanban card will work fine. If the habit isn’t there, you’ll need to add a reminder into how the team works already. But you might as well keep it there — it’ll be an important habit for new hires to learn as well.
But what if you’re not a manager? If you have time, you may not have to pitch it to your team or project lead and can take on the task yourself. You can still make an effort with your team members to add it as a requirement among yourselves. But if lack of time is the issue, then you’ll need to have a frank discussion with them in your next one-on-one to explain how much it potentially costs the company and team.
Setup For Success
Once you’ve documented old projects and built documentation as a habit in your new ones, your team has done themselves a huge service. Your team can be flexible and work where they’re needed or on the projects they want. They can adapt quickly and efficiently. And more importantly: they can focus more on building quality work, mentoring what matters, and solving problems than answering basic questions.
Documentation is just one step of the process, but it’s an important one. Don’t skip it! Your team’s future success will thank you.
