Making a business case for documentation, post 10 - Prepare to deal with objections

In the short term, yes, putting in processes for documentation may seem cumbersome. But the longer this is put off, the harder it will be to fix or create documentation. Much evidence points to the benefits of documentation in the long run. For example, teams with quality documentation are 2.4x more likely to meet or exceed their reliability targets: State of DevOps 2021 report, Google Cloud.

Emphasize that the "less is more" principle works well in documentation. Often it is better to produce less documentation (as long as it is high-quality, easy to refer to, and easy to update) rather than extensive unmaintained documentation that is unreliable. This is consistent with the approach proposed by Daniele Procida: Always complete, never finished.

Not all documentation is good documentation. Work out which documentation types provide a return on investment for your organization and then focus on that.

Yes, the value of good documentation is more challenging to measure than many other aspects of the business. However, just because it is challenging to measure doesn’t mean you are not experiencing the impacts (both positive and negative) of the quality of your documentation experience. Consider referencing case studies by others to predict your impact from documentation.

Or look at the following ways to measure the impact of documentation:

It’s a good idea to use Generative AI as an assistant in documentation efforts, but at the time of writing, Generative AI is still a way off from being able to produce reliable, reproducible content without oversight from writers or other stakeholders.

While Generative AI tools like ChatGPT and GitHub Copilot offer convenience and automation in generating text, they have notable limitations when it comes to producing quality documentation. For example:

Generative AI might work well for some use cases,such as documenting code and writing commit messages. But at the time of writing, it still needs human oversight.

Sure, when you have a small intuitive product and only a couple of users who you know personally, it is more efficient to explain things to them rather than write documentation. However, as things start to scale, the case for good docs keeps growing.

Initially, you can lean on your existing team to write docs and point them to The Good Docs Project templates to get started. As you grow, you’ll likely want to start investing in a tech writer.

Developers who write docs should use a modern documentation tool or format that technical writers can later take on as they start to enhance and scale up documentation. Incentives could also be given to community members to contribute to documentation.

Erin Grace has written a practical guide on how to determine the writer-to-developer ratio based on various factors: "audience-facing dev work, required documentation, relative experience, sprint cadence, developer and business analyst responsiveness, story quality, and existing documentation lag."

So instead of aiming for a specific ratio, focus on these indicators of a well-balanced documentation team:

Signs of strain include:

If you observe these signs, it may indicate a need for additional resources or process improvements.

The goal is to have a sustainable, effective documentation process, not to achieve a specific numerical ratio.

This kind of thinking, even if not acknowledged, can influence decisions about investing in documentation. It is, however, a short-sighted view.

Documentation should at least be good enough to help most typical users achieve most of their goals. If many users struggle to install the software or to figure out how to get started with it, that’s a documentation fault. With their frustration, they might not be willing to pay for training or support services. On the other hand, if a rather advanced user is trying to do innovative things with the software, they might be willing to pay for expert services.