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 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?

🎉 Series Complete! Just published the final post in my production-ready Spring Boot series: "How I document production-ready Spring Boot applications" After 25+ years of Java development, I've learned that great documentation is just as important as great code. This post shares my approach to making documentation a natural part of the development workflow. Key strategies covered: 📖 Documentation as Code - Store architecture docs in AsciiDoc format alongside source code in version control 🔄 Living API Documentation - Use Spring REST Docs to generate API documentation directly from tests, ensuring accuracy 📊 Visual Architecture - Create C4 diagrams with PlantUML that integrate into the Maven build process 🌐 Self-Serving Applications - Configure Spring Boot to serve documentation directly, making it easily accessible across environments The real value: When documentation lives with the code, it becomes part of the development process rather than an afterthought. New team members onboard faster, APIs are better understood, and architectural decisions are preserved for future developers. These practices transform basic Spring Boot applications into truly production-ready systems that teams can maintain and extend with confidence. For fellow developers: How do you approach documentation in your projects? I'd love to hear about strategies that have worked well for your teams. Full post: https://lnkd.in/ea64rcav #SpringBoot #Java #SoftwareArchitecture #Documentation #ProductionReady #DeveloperExperience

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.