The Problem
Most developers at some point have had the misfortune of inheriting a project that has little or no documentation or being asked to produce documentation for some level of management, and having to put it all together at the last minute. Documentation for software in companies, even companies that are not “software companies,” is an aspect of development that is often overlooked, even though its contribution to the development process and the business value delivered by software in an organization are significant.
The most common reason that many teams do not document their software products well is simple: without a documentation-oriented culture, it is often an afterthought and not baked into the development process. For developers, this often manifests the same way as having messy roommates (a situation many of us unfortunately can relate to). The pattern often goes like this: there is a mess because there are a handful of roommates and nobody knows who made the mess; because nobody knows who made the mess, nobody takes responsibility for the mess; and this leads to more and more messes people don’t take responsibility for. In the same way, software systems that are undocumented suffer from a creeping dread as developers know that there are no docs, and the task of being the one to start that process is daunting (and is it even their responsibility anyway?). If there is no proper time allocated to developing good documentation from the onset of a project, the problem grows like a weed.
The real costs of poor documentation are many and are, unfortunately, often very well hidden, scattered throughout an organization, and very difficult to piece together. Some really common ways that they rear their heads are things like onboarding times and repeated questions that could be in FAQs. One of the best ways to think about the value of good docs is imagining what would happen if an entire team won the lottery and disappeared today. Could the rest of the department work? Could the company? I have personally seen instances where the lottery factor for even individuals, not whole teams, could have cost companies millions. Another way to think about this is for developers who spend just 5 hours a week answering questions that could be documented, with 48 working weeks in a year, that developer has spent 240 hours of the year, or six full work weeks, just answering questions. That’s almost an entire PI’s worth of business value the company is not getting out of that developer, and we are all about delivering value.
Leadership Buy-In
To make the case to leadership for creating a documentation-oriented culture, we have to speak their language. Simply put, we have to put a dollar value on things. This can be done simply, as above, by calculating lost time. But we can also think about things in terms of risk mitigation. As in the aforementioned lottery scenario, what would actually happen if we lost key employees? Which systems are they key to? Is there some sort of plan for offboarding knowledge transfer? It helps by looking at the ROI the system is currently providing and putting it in terms like “If so and so leaves and this goes down, it’s going to potentially take us x number of weeks to figure out how this works so we can fix it.” Another element that we can put a dollar value on is the competitive advantage a company gets by the compounded time savings for developers and support staff; the less time spent answering questions and investigating systems, the more time that can be spent on innovation and value creation for the company.
The best way that leadership can respond to this is to be clear to project planners that time needs to be set aside for documentation, as well as having clear standards and expectations for what that documentation is. Time for documentation should always be a part of sprint planning, and developers need a clear idea of what their goals for creating documentation are. Another thing that leadership can do is to motivate those creating good docs by celebrating their wins. Company-wide kudos for those working hard to produce excellence can really boost morale and show developers that the time spent working on this is valued by both their peers and superiors.
Quick Wins
Creating documentation for a number of systems can be a very daunting task, and making tangible progress is very important for team morale, so it is often good to begin with quick wins. Generally, the biggest quick wins are going to be based on what the biggest pain points are, or what is hurting team ROI the most. Some good examples of this are documenting the onboarding process for each team or creating a wiki for frequently asked questions users may have. If there is a system that is confusing developers or stakeholders, go through and document the ones that generate the most questions. Another good idea for a place to begin is a “One-page initiative,” where each system gets a one-page overview and maybe a couple of FAQs. It’s important to remember teams don’t have to do it all at once, and incremental progress is better than no docs.
30 – 60 – 90 Day Plan
In addition to knocking out the quick wins, it’s always helpful to create a plan. In the words of Sun Tzu, “Let your plans be dark and impenetrable as night, and when you move, fall like a thunderbolt.” OK, that may be beside the point here, but it sounds cool, and planning is generally a good idea. The following is an example of what a 30/60/90 day plan may look like.
For the first 30 days, you generally want to focus on understanding where you are at, getting leadership buy-in, and identifying one or two quick wins. The leadership buy-in is absolutely essential. Without this element, it is extremely hard to justify to management why time is being allocated to work on these things. An audit doesn’t need to be completely comprehensive, but to solve a problem, you should have an idea of what your current state is, as well as what your goals are.
In the next 30 days, you may want to focus on building some standards for documentation. Define what needs to be done for a given project and how the docs should be written. Setting clear expectations and focusing on implementation with one team will give both management and developers an idea of what they can expect to work on and expect to see, and make decisions without having to roll back changes company-wide. This is the phase where people will create things like templates, wikis, and more, and decide how they should be filled in. It is important at this stage to celebrate the early wins. This really helps motivate the teams and highlight the value of work that may not have been highly valued in the past.
Finally, the templates and standards are rolled out to the rest of the teams. You’ll want to continue to celebrate wins and highlight the value of the work, and at this point, you should be able to begin gathering metrics. Time saved on questions, onboarding, research spikes, etc. The goal at this point is to make sure that all teams understand the value of good documentation and are implementing the agreed-upon standards as a regular part of their development cadence. Going forward, continuing to track metrics and iterate on feedback is essential to cultivating a continued culture of documentation excellence.
Conclusion
Most companies and their developers understand, at least in principle, that having good documentation is something that can contribute to the bottom line. The key to starting a culture of documentation excellence begins by coming up with a plan and implementing it with consistency. Needs may change over time, and the plan may change, but the time and cost savings will compound to deliver great value across any organization for every role involved.
