Why can’t you find the answers you need in the documentation?

“Click the ADD ENDPOINT button and add the URL,” the instructions say.

I look at every inch of the screen. There’s a button that says ADD DESTINATION, but when I click it there’s nothing about adding a URL, so that can’t be it.

I look through every menu. I scour the user forums. I ask ChatGPT, which tells me the button should be in the upper right corner of the screen. It is not. 

I give up and submit a ticket to tech support. A day later, I have a response: “Please use the ADD DESTINATION button to configure it. I’ll make sure to notify the documentation team about these changes to creating the Webhook integration, so they can update the documentation accordingly.”

Oh. Thanks.

Incomplete and out-of-date documentation is a leading cause of angst and suffering for everyday troubleshooters just trying to make things work. Why is this so frequently a problem?

Small Teams or Volunteers With Fragmented Knowledge

For many plugins, web apps, or tools, the developers are individuals or small teams with limited capacity, often pressured to move quickly and meet tight deadlines. Their time goes to development and support rather than keeping instructions updated. When it comes to WordPress and other open-source projects, much of the work is done by volunteers, who also have significant limits on their time and energy.

Often the people with the clearest understanding of how things work are not the ones writing the docs, and even when the information is out there, it can’t be found all in one place. Knowledge lives in forums and trouble tickets or left inside someone’s head, and never gets consolidated into the official docs.

Putting Out the Biggest Fires First

Users are more likely to complain about bugs or an inability to find something than they are to complain about confusing or missing instructions. For smaller projects, the same developers who are making the thing work are also in charge of explaining how it works. Given a choice between “make people stop complaining about the system crashing” and “update the docs to reflect that we’ve deprecated this feature in v12.4.1”, you can guess which will be a higher priority. Developers may not even know there’s an inaccuracy in the documentation, while in the meantime the occasional user who flounders through the documentation simply blames themselves and their own lack of understanding.

Documentation as an Afterthought

Writing clear, user-friendly docs is often undervalued. It’s not glamorous, it’s not half as sexy as announcing new features, and many teams don’t allocate enough time or resources for it. In some cases, documentation is written once during an early release and rarely maintained after that – meaning the “quick start” guide you’re trying to use gives instructions for last year’s interface, which don’t match the new version of the software you installed last month.

Writing Clear Instructions is a Special Skill

On top of that, good documentation requires clear writing, empathy, and structure. These are not necessarily the skills that a top-level programmer was hired for, and they may end up writing docs “off the side of their desk” in their spare time, making assumptions about the end-user and what they think they should already know. This disconnect often leads to cryptic, sparse, or overly technical instructions, full of jargon and missing important context.

Could AI write the docs for you? Sure, but don’t expect it to be much better. AI can only describe what it sees, and knows nothing about its context unless it’s integrated within a development workflow and trained appropriately. It doesn’t know what it’s writing documentation for, any more than you would if I pointed you at an app and said “show me how this works” (unless someone gives it instructions, thus defeating the purpose of having AI write the instructions). It can’t tell why a button is where it is, because it can’t see inside the developer’s thoughts. It can’t distinguish between “intended use” and “real-world use” and anticipate common pitfalls, confusing settings, or weird platform-specific behaviour. 

Besides that, good documentation is meant to be a guide, not a simple list of instructions. It’s about helping people out of the dark when they’re lost or anxious or frustrated. Well-written documentation should help the users throughout their journey to achieve a goal, to accomplish a task.

So you can’t find your way to your endpoint or a destination, or whatever the developers ended up calling it, don’t be afraid to reach out and ask them to point you in the right direction. More than likely, they’ll want to help you – and by improving their documentation, they’re improving their customer service and helping others as well.