Code Documentation in Agile Environments

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.

Top teams aren’t just documenting for today, they’re preparing for the future. For years, traditional documentation was the go-to approach. But as projects evolve, teams are adopting structured authoring and collaborative methods to keep up. If you want your team to stay efficient and scalable, You need to explore how these approaches can work for you. Each method has its strengths, But blending elements of all three often creates the best results. Here are 3 key approaches to consider: 📜 Traditional Documentation ↳ Standalone documents created independently. ⚙️ How it works: Content is written manually for each project. Formatting and style are managed document by document. ✅ Pros: ↳ Simple to get started. ↳ No specialized tools required. 🚫 Cons: ↳ Hard to scale across projects. ↳ Inconsistent formatting and style. 📈 How to improve: ↳ Use templates for consistency. ↳ Develop a basic style guide. 📂 Structured Authoring ↳ Modular, reusable content created using predefined frameworks. ⚙️ How it works: Content is written in chunks and assembled across outputs. Tools like DITA and MadCap Flare enable scalability. ✅ Pros: ↳ Increases efficiency and consistency. ↳ Scales well for large projects. 🚫 Cons: ↳ Requires specialized tools and training. ↳ Initial setup is time-intensive. 📈 How to adopt: ↳ Train your team in structured authoring tools. ↳ Build reusable templates for recurring content. 🤝 Collaborative Documentation ↳ Real-time content creation with multiple contributors. ⚙️ How it works: Teams collaborate using cloud-based tools like Confluence or Notion. Changes are visible and tracked in real time. ✅ Pros: ↳ Encourages faster feedback and updates. ↳ Ideal for agile workflows. 🚫 Cons: ↳ Version control can be tricky. ↳ Requires strong moderation to maintain organization. 📈 How to leverage: ↳ Establish clear roles and processes for contributors. ↳ Use tags and folders to keep content organized. Don’t limit your team by sticking to just one method. Many teams find success by combining elements of all three approaches based on project needs. What’s your team’s preferred documentation style? Let’s discuss in the comments! 👇 Want more career insights for writers: 1. Follow Joshua Gene Fechter 2. Like the post. 3. Repost to your network.

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.

Documentation isn't late. The product is. I posted last week about why documentation gets delayed. 40 professionals responded. Not one blamed the writing. The real answers: "Asking a technical writer to produce complete documentation without even providing access to the software." "Features that didn't make it into the preproduction environment during release week." "The customer requested a redesign a third of the way through the project." "They pushed this update live last night, documentation needs to be updated now." Am I missing something here, or is there a pattern forming? Writers are being asked to document products that don't exist yet. Then blamed when the docs aren't ready on time. Here's what's actually happening: Engineering ships features up to the hour of release. Writers get zero stable ground to document against. Screenshots become obsolete before review. And when a feature gets pulled last minute, nobody tells the writer who just spent two weeks documenting it. The fix isn't faster writing. It's earlier involvement. One commenter nailed it: make documentation part of the definition of done. Not a task that starts after development ends. A gate that runs alongside it. When writers get access to preproduction environments, participate in sprint demos, and see feature changes as they happen, documentation ships on time. Not because anyone wrote faster. Because someone finally gave them something stable to write about. When does your documentation team first see the product they're supposed to document? #TechnicalWriting #Documentation #ProductDevelopment #Agile #ProcessImprovement

Documentation isn’t about onboarding a new dev That’s what I used to think before starting Joggr, and I was wrong. Great documentation is the dev process. 📌 You start with requirements — written down, debated, agreed 📌 You move to design — document how you plan to build it, the tradeoffs, the reasoning 📌 Then code — with docstrings, comments, usage guides 📌 You ship — with feature docs, release notes, and how-tos 📌 And when it breaks? Runbooks. Alerts. Postmortems. All written down From idea to incident response, docs are the connective tissue. Skip one part, and the whole system gets shaky. Your team slows down. Your quality drops. It’s not about writing more. It’s about thinking clearly, sharing context, and building systems that scale. Where have docs saved you...or totally failed you?

Engineering teams are caught in a tug of war between getting new features out the door and creating documentation. Guess which I think should win! As a result, documentation debt can bite you when you need to onboard new team members and share knowledge. But what if documentation could be automated directly from the codebase, freeing up your devs to focus on what they’re best at? We built a proof-of-concept to put this idea to the test on an undocumented legacy codebase. Here’s how we did it: ↳ Grabbed the code and put it through Code2Prompt, an Open-Source tool selected because it allowed us to use private repositories essential for client work (this ruled out using Gitingest, for example) ↳ Transformed complex code into simple text - which, in a single, structured txt file, generates better results out of the LLM ↳ Took that txt file and added some of our best practice examples from past projects for training along with some prompts of our own ↳ Iterated, honing the prompt till we got a result we liked - which only took 5 attempts to get a useful first version, with most the changes focused on making sure the document was correctly structured The next step? We keep on iterating, with fresh rounds of testing, exploring how we can integrate AI documentation generation directly into deployment pipelines, to automatically update technical documentation as code evolves. We’ll share more takeaways as we continue with this experiment, but here’s one to start with: AI excels at creating structured overviews, eliminates "blank page syndrome", and highlights areas needing deeper investigation - but from there, it's on the humans to get business context and dive deeper. So all in all a very powerful accelerator without too much effort. Are you using AI to accelerate dev documentation? Let me know in the comments if you are (or if you want more details on the prompts we figured out).

A 60 page doc tripled this engineering team's velocity, I've been talking to engineering leaders for weeks, and there's a pattern nobody's discussing yet: teams aren't optimising for better code anymore. They're optimising for better documentation. They went from "we barely document anything" to maintaining a 60-page AGENTS.md file in just 3 months. Not user docs. Not API specs. Business logic documentation specifically for AI agents. These files include coding conventions, business logic, good vs bad examples, testing workflows, and architecture reasoning. What changed? They started using Cursor and Claude Code heavily. They realized something: when AI writes your code, the quality of what it produces correlates DIRECTLY with how well you explain your business logic. The shift is fundamental: Old way: Write code, document later (maybe) New way: Document first, let AI write the code Another team I spoke with now tracks "context quality" as a KPI. They're not measuring lines of code anymore , they're measuring how well their documentation helps AI understand what they're building. The bottleneck isn't coding speed anymore. It's context clarity. For engineering leaders using AI tools: are you seeing this pattern? How are you handling documentation? PS: if you’re a CTO/Engineering leader facing testing bottleneck and interested in shipping 10x faster, let's chat - https://lnkd.in/gJJUET-S

The closer technical writers are integrated with engineering teams, the better the documentation becomes. When writers are treated as essential members of the development process rather than an afterthought, they can create more accurate, timely, and valuable documentation that truly serves both users and developers. Docs-as-code is one of the most effective ways to achieve this integration. By using the same tools and workflows as developers, technical writers can participate directly in the software development lifecycle, catch documentation needs earlier, and maintain docs with the same rigor as code. For teams looking to get started with docs-as-code, here are some excellent tools to consider: Static Site Generators: - Jekyll (particularly with GitHub Pages) - MkDocs - Hugo - Sphinx (especially for Python projects) Documentation Linters: - Vale for style/grammar checking - markdownlint for Markdown consistency - awesome-lint for README files Version Control & Collaboration: - GitHub/GitLab for repository management - Pull request workflows for doc reviews - GitHub Actions for automated doc testing - LEARN GIT VIA COMMAND LINE The investment in learning these tools pays off quickly in improved #documentation quality, better collaboration with developers, and more efficient workflows. Most of these tools are open-source and well-documented, making them perfect for teams just starting their docs-as-code journey. #TechnicalWriting #DocsAsCode #Documentation #TechComm #DeveloperDocs #TechnicalCommunication