Advocating for Documentation - What, Why, and How?

This topic isn’t the easiest to write about—because we’re not living in an ideal world. Real-life workplaces often involve competing priorities, tight deadlines, and differing views on the value of documentation. But that’s exactly why advocating for documentation is so important.

But don't worry, this isn’t a philosophical piece. I want to be clear that this article won’t solve the problem in every scenario. The work of a tech writer is too diverse for a one-size-fits-all solution. But trying is what really makes a difference. Advocacy for documentation starts with small steps, persistence, and a willingness to champion its value—even when it feels like an uphill battle. If you’re reading this and considering how to embrace documentation efforts in your role, you’re already on the right track. Thank you for being interested.🤗

What does advocating for documentation really mean?

At its core, advocating for documentation is about being the person who stands up and says, “Enough of this chaos—let’s make it organized.” It's about convincing stakeholders that absence of documentation is a bug, not a feature. Advocacy is about reframing documentation as an asset that saves time, reduces costs, and improves user satisfaction.

Now, let's get to the "Why" part.

Why does documentation need advocacy?

You might be wondering, If no one else cares, why should I? I’ve asked myself this question, too. I’m the kind of person who always needs the “why” question answered to truly grasp the purpose and mission behind something. For me, the answer lies in examining the challenges companies face in delivering high-quality products that people can easily understand and genuinely enjoy using.

Let me share the most common objections to documentation:

• “Not enough time.” Teams prioritize development over documentation, believing it’s more important to “ship the product.”
• “It’s obvious.” The assumption is that code, or features are self-explanatory.
• “We’ve done this before, and it’s working.” Resistance to change often comes from past successes, even if they’re not scalable.
• “ChatGPT (or other tools) can explain it.” Assuming the user is up to search for answers writing prompts and find the information that can't be even there.
• "A quick call will be enough if any questions arise." Because people have a perfect memory, right? 💁🏽‍♀️

The wording can vary, but the sense is always the same.

Now, let’s move on to the “How”.

How to advocate for documentation

Let’s tackle each objection one by one.

Not enough time

When teams claim there’s no time for documentation, they’re often focused on short-term goals.

What you can do here is try to tie documentation to efficiency. Explain how documentation reduces repetitive questions and onboarding time for new hires. Suggest writing documentation alongside development. For example, create templates for engineers to fill out as they code.

Ask folks from support how often they receive repetitive questions or need to explain the same issue multiple times—this data can be a compelling argument for the time-saving benefits of documentation.

I'd say something like: "I understand we’re on a tight timeline, but if we take 30 minutes now to document this process, we’ll save hours in onboarding the next team member or handling support tickets later.”

It's obvious

What’s obvious to one person may be completely confusing to another. Assumptions often fail because people come from different backgrounds, perspectives, and levels of expertise.

Try testing this assumption. Ask a colleague unfamiliar with the project to follow the process or use the feature without guidance. Their struggles will highlight gaps.

Like: "Let’s do a quick experiment. I’ll hand this feature to someone in another team and ask them to use it without instructions. If they struggle, it’s a sign we need documentation.”

We’ve done this before and it’s working

Past success doesn’t always mean current practices are optimal—after all, half the companies out there are still running critical processes on an Excel sheet from 2010 that no one dares to touch. But times are changing, technologies are advancing, and documentation needs to be evolving right alongside them.

So, try focusing on scalability. Point out how undocumented processes become bottlenecks as teams or products grow. Share specific instances where lack of documentation caused confusion or delays. Who knows? Maybe one day the stakeholders will see things differently and realize you can’t have solid growth without proper documentation—hopefully before it’s too late.

ChatGPT will explain it

This is the argument I’ve been hearing the most lately. And sure, there’s some truth to it—AI-powered tools can be incredibly effective for explaining general concepts. I use them all the time myself, and they’re great for that purpose.

However, when it comes to new technologies or project-specific details, tools like ChatGPT can sometimes "hallucinate" answers, creating information that’s misleading or even completely incorrect. Instead of helping, this can end up confusing the reader even more.

If the information isn’t documented, it simply doesn’t exist for the AI to reference. This is where incorporating Retrieval-Augmented Generation (RAG) searches into an existing knowledge base becomes invaluable. In my opinion, this approach represents the real future of tech documentation — blending AI capabilities with a well-maintained source of truth.

That said, it’s important to remember: AI won’t generate what’s not there. In this industry, context and nuanced scenarios are critical. General AI tools can't match the depth of understanding and specific knowledge that comes from thorough documentation. They might be able to process information and generate text, but they can't replicate the nuanced insights and edge cases that only human experts can provide.

A quick call will be enough

Calls may resolve immediate questions, but they’re not scalable or efficient in the long run.

Explain how documentation saves time by providing instant answers without interrupting others. One call might work for a single question, but what happens when multiple people need answers at different times? Documentation ensures everyone has access to the same information without scheduling conflicts.

And as I already stated, people forget. Even the best call recap can miss crucial details, leaving teams confused when the memory of that "quick call" fades. Documentation creates a reliable, searchable resource that lasts beyond the moment.

Persistance is key

Not every attempt will succeed, but each small win—whether it’s a single process documented or a stakeholder convinced—contributes to a culture that values clarity and organization.

So, keep advocating. Keep pushing for clarity in a chaotic world. And remember: You’re already a great writer for taking the first step toward embracing documentation as a critical part of any project.