The Secret Life of Claude Code: Using AI to Write Documentation
.jpeg)
The Secret Life of Claude Code: Using AI to Write Documentation
How to use Claude Code to keep your docs synchronized with your codebase
#ClaudeCode #CodingWithAI #Documentation #SoftwareEngineering
Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where code quality is the unspoken objective, and craftsmanship is the only thing that matters.
Episode 15
Dusk had arrived properly at last, and with it the particular quality of evening light that made the library feel older than it was — the lamps warmer, the shadows deeper, the shelves more permanent. Timothy arrived to find Margaret at her usual table with an unusual companion: a stack of printed pages, heavily annotated, covered in her precise handwriting in three different colors of ink.
He sat down and looked at the pages without touching them.
"That looks like a considerable amount of work," he said.
"It is the documentation for a system I worked on several years ago," Margaret said. "I was asked to review it this week. To see whether it still accurately describes what the system does."
"And does it?"
Margaret looked at the pages for a moment. "It describes what the system did when it was written. In the years since, the system has changed considerably. The documentation has not changed at all." She set her pen down. "It is not wrong, exactly. It is something more insidious than wrong. It is confidently, precisely, beautifully wrong."
Timothy understood the particular frustration in her voice. He had encountered documentation like that — detailed, well-written, clearly the product of real effort, and almost entirely misleading because the system it described no longer existed.
"It lies with authority," he said.
"Yes. That is exactly what it does."
Staying Current
"How does it happen?" Timothy asked. "The drift. Everyone knows documentation should be kept current. And yet."
"And yet," Margaret agreed. "The reasons are not mysterious. Documentation is written at the moment of maximum understanding — when the system is new, when the decisions are fresh, when the person who built it is still present and can explain it. And then the system changes, and the documentation does not, because changing the documentation feels like overhead. The feature is done. The tests pass. The documentation update is the last item on the list and the first to be deferred."
"Until the list is long enough that nobody remembers it exists," Timothy said.
"Yes. And by then the documentation has become a liability rather than an asset. It does not just fail to help — it actively misleads. A new developer reads it, trusts it, and builds something on a foundation that no longer exists." She paused. "The most dangerous documentation is not the missing kind. It is the present, detailed, outdated kind."
Timothy thought of the number of times he had spent an hour following documentation only to discover that the system it described had been refactored two years ago. The documentation had cost him more time than having no documentation at all.
"The absence of documentation is at least honest," he said.
"It is," Margaret said. "Which is a sad thing to have to say about a practice that exists to help people."
What to Contain
"Where does Claude Code enter this?" Timothy asked.
"In several places," Margaret said. "The first and most immediate is the cost of writing documentation in the first place. Good documentation has always been expensive — it requires time, clarity, and the discipline to explain something you already understand to someone who does not. Claude Code reduces that cost considerably."
"You describe the system, it drafts the documentation," Timothy said.
"More precisely — you describe what the system does, what decisions were made and why, what constraints exist, what a new developer would need to know to work with it safely. And Claude Code turns that into documentation that is clear, structured, and complete." She paused. "The thinking is still yours. The articulation is assisted. And the result is documentation that would have taken an hour to write taking fifteen minutes."
"Which means the excuse of not having time is harder to sustain," Timothy said.
"Yes. But there is something more valuable than speed," Margaret said. "Claude Code can help you identify what the documentation should contain — which is often the harder problem. Most developers who sit down to write documentation discover that they don't know where to start. What is obvious to them may not be obvious to the next person. What seems unimportant may be critical. Claude Code, asked the right questions, will tell you what a new developer working with this system would need to know. It will ask you the questions you didn't think to answer."
Remaining True
"There is a second use," Margaret said, "that I have been thinking about this week more than usual." She gestured at the annotated pages. "Documentation review. Not writing new documentation — reviewing existing documentation against the current state of the system."
"Asking Claude Code whether the documentation is still true," Timothy said.
"Yes. You provide the documentation and the current code, and you ask it to identify discrepancies. Where does the documentation describe behavior the code no longer exhibits? Where does the code do things the documentation does not mention?" She paused. "It will not catch everything. But it will catch the obvious drifts — the function signatures that have changed, the parameters that no longer exist, the workflows that have been replaced."
"A first pass before the human review," Timothy said.
"An efficient first pass. The kind of review that would take a senior developer half a day to do manually, Claude Code can do in minutes. What remains for the human is the judgment — the assessment of whether the discrepancies matter, which ones represent genuine problems, what needs to be updated and what can be retired." She looked at the annotated pages. "I spent two days on this. With Claude Code, the first pass would have taken an hour. The judgment would still have been mine. But the mechanical comparison — line by line, claim by claim — that is work Claude Code can do."
A Thinking Tool
"I want to suggest something," Timothy said slowly, "that I haven't fully worked out yet."
Margaret waited.
"We talked about testing as thinking — the idea that writing a test isn't just verification, it's a way of understanding the problem more precisely." He paused. "I think documentation might work the same way. Writing documentation for something you've just built forces you to explain it — and in explaining it, you sometimes find that you can't. That there are parts you don't fully understand. Decisions you made by instinct that you can't articulate."
"And the inability to articulate them is a signal," Margaret said.
"That you don't understand them as well as you thought," Timothy said. "Or that the decision was wrong and wouldn't survive being written down."
Margaret looked at him with quiet attention. "This is one of the oldest observations about writing — that the act of writing something down reveals whether you actually understand it. Code can hide incomplete understanding. Tests can hide it. Documentation cannot, because documentation requires you to explain not just what the system does but why." She paused. "A decision that cannot be documented is a decision that cannot be defended. And a decision that cannot be defended is worth revisiting."
Timothy thought of a data model he had designed three weeks ago. He had been confident about it. He had not been able to explain the key architectural choice to his colleague in a way that satisfied either of them. He had moved on anyway.
"I should have written it down before I moved on," he said.
"You should have tried to," Margaret said. "The trying would have been enough. Either you would have found the words — and understood the decision better — or you would have found that the words weren't there. And that would have told you something important."
Proof of Understanding
"The title of the problem," Timothy said. "How do you keep it true? Not just write it well initially, but keep it current."
"The discipline has two parts," Margaret said. "The first is proximity — documentation updated at the same time as the code, as part of the same task, not deferred to a separate effort that never happens. Claude Code helps here because it lowers the cost of the update. When you change a function, you ask Claude Code to update the relevant documentation section. It takes minutes rather than the hour that makes it easy to defer."
"Making the update the natural conclusion of the task rather than an afterthought," Timothy said.
"Yes. The second part is ownership — treating documentation as a living artifact with the same status as code. Not a byproduct of the work. Part of the work." She looked at him. "A system that works but cannot be explained is only partially complete. The explanation is the other half. And Claude Code, for the first time, makes the other half achievable at a cost that does not make it feel like a punishment."
Timothy sat with this for a moment. He had always thought of documentation as the virtuous thing he never quite had time for. He was beginning to understand it differently — not as overhead, but as the evidence that understanding was complete. The test that the thinking had been finished.
"Documentation isn't the record of the work," he said. "It's the proof that the work was understood."
Margaret looked at him steadily. "That is the best definition of it I have heard," she said. "Yes."
A Clean Page
Timothy gathered his things, the library quiet around him, the annotated pages still spread across Margaret's table like a map of a territory that had moved on without them.
"Will you update it?" he said. "The documentation."
"I will recommend that it be retired and rewritten," Margaret said. "What is there now is too far from the truth to be salvaged by editing. Sometimes the kindest thing you can do with documentation that has drifted too far is to acknowledge that it is no longer describing anything real — and start again with what is."
"A clean page," Timothy said.
"With better habits this time," Margaret said. "That is all documentation ever asks."
He walked to the tall doors, the autumn evening outside sharp and clear after the warmth of the library, the first few leaves beginning their long slow letting go.
Behind him, Margaret uncapped a fresh pen and turned to a clean sheet of paper.
Next episode: Margaret and Timothy turn to the legacy codebase — what it means to work with code you didn't write, systems you don't fully understand, and how Claude Code changes the experience of inheriting someone else's decisions.
Aaron Rose is a software engineer and technology writer at tech-reader.blog.
Catch up on the latest explainer videos, podcasts, and industry discussions below.
Comments
Post a Comment