Stop Generating More Documentation. Start Transferring Knowledge.

I haven't seen many people talk about this, but based on my experience, I can say that a lot of documentation we currently see in software projects, or even in other places, really sucks. I've seen documents with a lot of technical details that still fail to explain what actually matters.

If anyone thinks that typing is the hardest part of writing documentation, they're completely wrong. Now AI can generate whatever text you want, even a 30-page document in a minute, but that doesn't mean it's actually useful. The goal of technical documentation, or whatever is shared as a document, is to transfer knowledge to another person.

Of course, I use AI myself to help me write documentation, like fixing grammar and typos, using speech-to-text instead of typing, or sometimes improving sentences. So, I don't think avoiding AI completely is the right approach either. But I think there's a big difference between using AI to help you write documentation and just asking it to generate an entire document with a simple prompt.

Longer Isn't Always Better

People often assume that generating documents makes life easier for others. But in many cases, what you get is just a long document that, even after spending a lot of time reading it, you still can't understand the point of it.

Because most people reading this article are probably software engineers, I want to explain this concept with a simple example. If exposing a lot of data and information were always a good thing, we wouldn't have invented abstraction in software engineering. We don't need to expose every detail of a system to someone who just wants to understand or use a specific part of it.

I think the same principle applies to documentation. You don't need to put everything into one document just because AI can generate it.

A longer document doesn't necessarily mean a better document. It's similar to measuring code quality by the number of lines of code. Everyone knows that more lines don't necessarily mean better code. The same goes for documentation. Maybe you've just wasted a lot of tokens.

A longer document doesn't necessarily mean a better document.

AI Doesn't Have All Your Context

When you want to use an AI tool to write the document, there's an important question: Does the AI tool have all the context it needs?

For example, imagine you have a codebase and ask an AI tool to generate documentation based on it. But as someone who has worked on that project, you have a lot of additional context that isn't available in the codebase.

From the codebase, you can understand how the system is implemented, but you might not know why it was implemented that way instead of another way. This could be an important point to include in the documentation.

So, you can't rely only on the codebase as context. Maybe you need to provide more information in your prompt or include other documents alongside the codebase to generate useful documentation.

You can't expect an AI tool to do miracles just because it has access to your codebase.

From the codebase, you can understand how the system is implemented, but you might not know why it was implemented that way instead of another way.

Know Your Audience: Humans or LLMs?

Another important point about the audience is that you might not even be writing documentation for people. Maybe you're writing it for another agent to use as context. And depending on the audience, you might need a different approach.

If you're writing documentation for another AI agent, you might need to use a different structure, different level of detail, or even follow specific rules to make the information easier for the agent to understand and use. For example, when writing specifications for spec-driven development, you might want to follow a more structured format. You can use terms like MUST, SHOULD, and MAY, as commonly used in RFCs, to make requirements clearer. This can help reduce ambiguity for both people and AI agents. Sometimes you need a high-level architecture document, like the one described in ARCHITECTURE.md, while other times you need more detailed documentation.

When you're writing for people, you don't necessarily need to follow the same approach. You need to think about how they will read the document, what they already know, and what they actually need to understand. Sometimes, a simple diagram can explain something better than many paragraphs of text.

Conclusion

So before writing a document, you need to understand a few things. Who is your audience? What knowledge do you want to transfer to them? Which parts of the topic you want to explain are more important? What level of abstraction should the document have?

After answering these questions, you can write a document that's actually useful for others instead of wasting their time.

Think about it: if your document wastes just 10 extra minutes for each reader, and 1,000 people read it, you've wasted more than 166 hours of other people's time.

That's why I think this is such an important point. Sometimes, one well-written paragraph can transfer as much knowledge as two pages of poorly written documentation.

So again, I don't think writing documentation can be completely outsourced to an AI agent in every case. You can outsource the typing to AI, but you can't completely outsource the thinking.