You can lead a horse to water, but you can’t make it drink. In this metaphor, technical documentation is the water.

You can spend a lot of time making the pond look nice and accessible. Provide clear, clean water, some lily pads, a water feature to make it easier to drink. You invest in the structure of the pond to make sure the water doesn’t get stagnant, and even add a nice sign to indicate “fresh water here”.

But if the route to the pond is treacherous — difficult to follow, unclear, full of pitfalls — then the horses won’t visit your beautifully curated pond. You won’t be able to lead the horse to the pond with the fresh, high-quality water. Instead, the horses will drink out of a muddy puddle — because the puddle is right in front of them where they were going already.

I’m stretching this metaphor to its limits to underscore the importance of having a content strategy. It’s not enough to write effective, accurate, and useful content. You also need to identify how people discover your content — invest in documentation discovery and evangelism.

If people don’t know how to get to your content, if it doesn’t appear in their pre-existing paths, they won’t discover it. And if they don’t know what’s in it or what the quality of your content is, they won’t use it.

Consider the context #

When you write documentation, you must consider the context in which it exists:

• How do customers learn about your product?
• How do they discover helpful content?
• What do they do when they have a question?
• Where do they go for help when they get stuck?

If your documentation isn’t available and accessible where your customers need it, it almost doesn’t matter what you write because it won’t get used.

Instead, customers will turn to alternatives:

• Google search AI overview
• Chat support with live humans
• LLM-based chat interactions like ChatGPT or Claude
• Training from third-party consultants
• Blog posts published on your company website
• Videos created by external developers

These content types can be useful, but many of them are expensive to provide (and access) and are frequently not well maintained. Resources that are only available to some folks or are outdated are not as useful, reliable, or authoritative as official documentation. And if customers are using these content types instead of rather than in addition to the official documentation, you have a problem.

Improve access and awareness #

So what can you do?

• Ask people what they do when they get stuck. If they don’t mention the documentation, ask them why — identify the hurdles hindering access to the pond.
• Make the documentation easy to get to. Pave the way to the beautiful pond you’ve curated by adding entry points like links from the website and the product and improving SEO.
• Evangelize the documentation. Tell people about it, talk about the great resources available internally to the folks that interact directly with customers.
• Shift priorities to focus on enhancing discovery instead of writing feature-driven content. Accept that the pond can grow some algae as long as the water remains potable.

You might discover when you talk to customers and internal stakeholders that the documentation you thought was excellent isn’t actually fitting the need — maybe the pond is too shallow to provide effective hydration to the horses, or the shoreline is difficult to access, or only some horses can find their way to the pond.

Getting feedback can help you prioritize your work accordingly to help ensure that your documentation gets used. If your technical content isn’t available where your users look for it, your content won’t get used — no matter how good it is.

Humans are creatures of convenience. Build your beautiful pond, but don’t forget to make it easy to access.