Treating Code as Documentation in Software Development

We thought our first AI project would be something exciting. It turned out to be documentation. When we started mapping our processes for AI, we hit a wall nobody expected. Our knowledge was scattered across Notion, Google Drive, Slack, and most of it lived in people's heads. We interviewed about 30 team members. Documentation came up in every single conversation as the core problem. Not a side issue. THE issue. One team member put it simply: "Documentation is a phantom. The company has never found a methodology to maintain it." Another described spending 30 minutes searching for something that should take 2 minutes. We counted at least 5 previous attempts to fix this. None really successful. So we started over, but differently. A knowledge base should not be a tool. It's an abstraction. You ask a question, you get an answer. You don't need to know where the document lives, which platform it's stored on, or read through pages to find what you need. A single intelligent layer queries documentation, structured data, and production systems at once. Visualizations are generated on demand, always up to date because they're computed, not manually maintained. To make this work, we had to clean the foundation first. AI generates initial documentation from existing sources, old Notion pages, Slack threads, production data, interview notes. Domain owners validate in 30 minutes instead of writing from scratch for hours. For our engineering documentation, we went further. We extract documentation directly from the codebase. Code is the single source of truth. AI wrote and verified it. Automated workflows keep it synced. As the code evolves, AI agents update the docs. 31 microservices, 212 features and resources documented this way. It doesn't go stale because it's never manually written. Then we protect what's been cleaned. Agentic feedback loops detect staleness. Every document has two owners, so knowledge survives if someone leaves. We measure documentation health the same way we measure code quality. The metric is simple: can people find answers without asking someone? We went from a knowledge base where everything contradicted everything to a system where AI can actually reason over trustworthy information. This was the unsexy first step of our AI transformation. No model selection, no prompt engineering, no automation. Just making our knowledge accessible, consistent, and trustworthy. Everything we're building now depends on this foundation. More on that next week.

The problem with keeping code and documentation separate. It tends to diverge over time. So most software documentation should be replaced with highly readable code and tests. However, no matter how readable the code is, it doesn’t give us the context behind why the code exists in the form that it does. To address this software engineering teams should be keeping Architecture Decision Records (ADRs). These are lightweight documents that capture important architectural decisions along with the when, how and why of the decision. ADRs are particularly useful for agile projects where not all the decisions will be made at once and long lifetime projects where a new person joining the team, or someone who hasn’t worked on part of the project recently, will need to understand the rationale and consequences of a decision that has been made in the past. An ADR should record: 1. When the decision was made. 2. The status of the ADR (proposed, accepted, rejected, etc.). 3. The current context and business priorities that relate to the decision. 4. The decision and what will be done because of the decision. 5. The consequences of making the architectural decision. ADRs are best stored in the revision control system alongside the code that they relate to, keeping the context with the code.

I work at Airbnb where I use LLMs to add features to huge codebases with custom libraries and APIs. LLMs aren't only for new projects. Here is my workflow: Treat the LLM like a new developer that needs to ramp up on the project 𝟭. 𝗦𝘁𝗮𝗿𝘁 𝘄𝗶𝘁𝗵 𝗮 𝘀𝗽𝗲𝗰𝗶𝗳𝗶𝗰 𝗲𝗻𝘁𝗿𝘆 𝗽𝗼𝗶𝗻𝘁 I ask my coding agent to start at the root directory and read a specific file path related to the feature or area I’m working on. From there, I have it trace the code and its dependencies so it can understand how the system fits together. 𝟮. 𝗚𝗲𝗻𝗲𝗿𝗮𝘁𝗲 𝗶𝗻𝘁𝗲𝗿𝗻𝗮𝗹 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 I ask the agent to crawl through the codebase and draft documentation explaining how that feature or area works. It looks at imported libraries, API schemas, shared utilities, common patterns, endpoints, and related functions. Basically, it does what a human engineer would do when ramping up on an unfamiliar part of the codebase without much documentation. 𝟯. 𝗪𝗿𝗶𝘁𝗲 𝘁𝗵𝗲 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝘁𝗼 𝗱𝗶𝘀𝗸 I have the agent save the output into a docs/ folder. This can include written explanations, implementation notes, and Mermaid diagrams that show how components relate to each other. That documentation becomes reusable context for the rest of the task. 𝟰. 𝗥𝗲𝘃𝗶𝘀𝗲 𝘁𝗵𝗲 𝗱𝗼𝗰𝘀 𝗮𝘀 𝗻𝗲𝗲𝗱𝗲𝗱 The first version is rarely perfect, so I review and refine it. Once it’s accurate, I can ask the LLM to read those docs before implementing the feature. From that point on, it has much better context for the codebase. 𝟱. 𝗔𝗱𝗱 𝘁𝗵𝗶𝗿𝗱-𝗽𝗮𝗿𝘁𝘆 𝗹𝗶𝗯𝗿𝗮𝗿𝘆 𝗰𝗼𝗻𝘁𝗲𝘅𝘁 When I’m using an external library, I point the agent to the relevant external documentation pages. Then I ask it to summarize the important methods, APIs, return values, examples, and best practices into another file in the docs/ folder. This helps the agent understand not just our codebase, but also the tools it needs to use correctly. 𝟲. 𝗨𝘀𝗲 𝗰𝗵𝗮𝘁 𝗽𝗿𝗼𝗱𝘂𝗰𝘁𝘀 𝘄𝗵𝗲𝗻 𝗻𝗲𝘁𝘄𝗼𝗿𝗸 𝗮𝗰𝗰𝗲𝘀𝘀 𝗶𝘀 𝗹𝗶𝗺𝗶𝘁𝗲𝗱 If the coding agent doesn’t have network access, I do this step manually with ChatGPT, Gemini, or Claude. I drop in the relevant docs link and ask for a concise summary focused on the APIs and patterns I’ll need. For this kind of deep documentation and codebase-understanding work, I’ve found GPT-5 Pro, Gemini 3 Pro, and Opus 4.7 with extended thinking especially useful.

I used to think documentation was for people who couldn't remember their own code. Spoiler alert: I am those people. Six months ago, I built a feature I was ridiculously proud of. Clean architecture, elegant solutions, the whole nine yards. Wrote exactly zero documentation because "the code is self-explanatory." Fast forward to last Tuesday: Got asked to modify that exact feature. Opened the codebase. Stared at my own code like it was written in ancient hieroglyphics. Spent 4 hours reverse-engineering my own logic like I was cracking the Da Vinci Code. The kicker? Found a comment that said "TODO: Document this later." Past-me was an optimist. And an idiot. What I learned the hard way: → "Self-documenting code" is a myth we tell ourselves to avoid writing docs → Your confident present self and confused future self are basically different people → Comments explaining "why" matter more than comments explaining "what" → If you have to spend more than 5 minutes understanding your own code, document it → Future-you will either thank you or curse you - there's no middle ground My new documentation philosophy: Write docs like you're leaving angry notes for a version of yourself who's already forgotten everything and is working under a deadline. Because that's exactly who's going to read them. Now I document aggressively. Not because I'm organized. Because I'm realistic about my memory. The code explains what it does. The documentation explains why it exists. What's your worst "I wish past-me had documented this" moment?

Technical writers often struggle with the documentation process. But I don't... Here's why: I don't use neglected, out-of-sync docs. There's no need to treat documentation as an afterthought, losing countless hours to outdated information and miscommunication. Now, we're using Docs as Code—a trend that has changed how technical writers, developers, and stakeholders collaborate on documentation. Docs as Code means treating your documentation with the same respect and processes as your code. Same tools, same processes, same love and attention. By doing this, you integrate documentation into the development process, making it a native. As a result, you get to: → Use Git-based version control for your docs → Deploy updated documentation automatically → Allow your entire team to contribute effortlessly → Reduce tickets caused by outdated documentation → Implement review processes for documentation changes → Ensure users always have access to up-to-date information → Eliminate conflicting information across different doc versions → Track changes, manage branches, and resolve conflicts → Set up continuous integration to test for broken links → Maintain a single source of truth that you can trust → Automate doc generation from code comments → Keep your docs in lockstep with your codebase And the implementation isn't rocket science as well—it's more straightforward than you might think. Never treat your documentation like an afterthought—it's an integral part of your product. By treating docs like code, you'll: > 𝐒𝐥𝐚𝐬𝐡 𝐭𝐢𝐦𝐞-𝐭𝐨-𝐦𝐚𝐫𝐤𝐞𝐭 𝐛𝐲 𝐮𝐩 𝐭𝐨 50% > 𝐁𝐨𝐨𝐬𝐭 𝐩𝐫𝐨𝐝𝐮𝐜𝐭 𝐪𝐮𝐚𝐥𝐢𝐭𝐲 𝐚𝐧𝐝 𝐫𝐞𝐝𝐮𝐜𝐞 𝐞𝐫𝐫𝐨𝐫𝐬 𝐛𝐲 30% > 𝐒𝐤𝐲𝐫𝐨𝐜𝐤𝐞𝐭 𝐮𝐬𝐞𝐫 𝐬𝐚𝐭𝐢𝐬𝐟𝐚𝐜𝐭𝐢𝐨𝐧, 𝐛𝐨𝐨𝐬𝐭𝐢𝐧𝐠 𝐜𝐮𝐬𝐭𝐨𝐦𝐞𝐫 𝐫𝐞𝐭𝐞𝐧𝐭𝐢𝐨𝐧 𝐛𝐲 25% Stop losing money on inefficient documentation processes and start delivering value faster. Share your thoughts or experiences with Docs as Code in the comments. Have you implemented this approach?

Your code should explain what it does. Your docs should explain why it exists. If you're writing comments that describe what the code does, you're fixing the wrong problem. The code should be clear enough that it doesn't need explanation. Good variable names beat comments. A well-named function beats a paragraph explaining what it does. But here's what code can't tell you: Why you chose this approach over the alternatives. The code shows the solution. It doesn't show the three other approaches you tried that didn't work. What tradeoffs you made. "We're using polling instead of webhooks" is visible in the code. "We chose polling because the third-party API has unreliable webhook delivery" isn't. What constraints shaped the decision. The code shows a simple implementation. It doesn't show that you kept it simple because the team is small and complex would slow everyone down. I've seen engineers spend hours trying to understand why code is "wrong" when it was actually right given constraints they didn't know about. The worst documentation I've seen: Comments that repeat the code. The best documentation I've seen: Three sentences explaining why this approach, not that approach. Document decisions, not implementations. The code will change. The reasoning behind it shouldn't disappear. If future-you can't remember why you built it this way, future-someone-else definitely won't figure it out. How do you decide what's worth documenting? #SoftwareEngineering #TechnicalWriting #EngineeringLeadership

A senior engineer joined a team I was advising. First week, he spotted a weird workaround in the payment flow. He cleaned it up. Payments broke on a Friday at 4:55 PM. $47K in failed transactions before anyone caught it. The workaround existed because the payment provider times out on large carts. The retry logic caused double charges. The workaround prevented duplicates. Nobody had written that down anywhere. The team learned the same lesson twice. Once in production. Once in the postmortem. Here's the documentation problem most teams don't see: Skip it → institutional knowledge disappears the moment someone leaves. Document everything → shipping slows to a crawl. Docs drift. Reality moves faster than Confluence. The fix is a 3-part minimum documentation standard: The decision — What did we choose? What did we rule out? "We kept the workaround in the payment flow." The reason — Why does this exist? What constraint forced it? "Provider times out on large carts. Retry logic caused duplicate charges." The consequences — What breaks if someone removes this? When to revisit? "If removed, duplicates return. Revisit when provider supports idempotency keys." Three parts. One page. One link in the PR. What to document every time: ✓ Architecture decisions that change the shape of the system ✓ Weird workarounds that look wrong but are right ✓ External constraints — vendors, compliance, rate limits ✓ Public contracts — APIs, events, schemas What to stop documenting: ✗ UI screenshots of interfaces that change weekly ✗ "How to set up the repo" essays nobody updates ✗ Meeting notes with no decisions ✗ Anything that duplicates what the code already says Ship the software. Document the why. Skip the rest.

The shift from traditional DITA/XML #documentation pipelines to a docs-as-code approach represents a significant evolution in technical writing. By treating documentation like code, we can streamline their content development while improving collaboration and quality. Markdown has emerged as the clear winner for modern documentation (this isn't new news, markdown has been the de-facto go-to for years now), offering a clean, readable syntax that's both human and machine-friendly. When combined with Git version control, technical writers gain powerful capabilities like branching, meaningful version history, and the ability to handle concurrent updates seamlessly. Documentation linters add another layer of consistency by automatically checking for style guide violations, broken links, and formatting issues before content goes live. Unlike rigid DITA/XML workflows that often require specialized tools and expertise, docs-as-code leverages the same tools developers use daily. This alignment not only reduces tooling costs but also breaks down silos between technical writers and development teams. Docs-as-code is also just faster and more efficient than DITA, in my experience. It leads to simpler, cleaner docs through and through. The result? Faster documentation cycles, better collaboration, and the ability to maintain documentation at the speed of software development. As someone who's witnessed this transformation firsthand, I can't imagine going back to the complexity and constraints of traditional XML-based workflows. Push for modern documentation practices at your org. The future isn't tomorrow, it's today so modernize your docs workflows and tooling! #TechnicalWriting #DocsAsCode #Documentation #TechComm #DevDocs #Tech #Engineering