Best Practices in Open Source Code Documentation

You write your docs in Markdown (or mdx), right next to your code... You're already winning. It's the best way to keep docs current and part of the development workflow. But let's be honest. Sometimes that docs/ folder becomes a chaotic mess of untitled files and outdated notes that only you understand. Writing docs next to code is the first step. Making them useful is the master stroke. Here are 5 tips to level up your docs-as-code game. 1️⃣ Document the "Why," Not Just the "What." Your code is the "what." It's explicit. Don't write docs that just re-explain what a function does. Your code should be clean enough for that. Write down the why. "Why did we choose Kafka over RabbitMQ for this service?" "What business logic led to this weird edge case?" A single sentence of context is worth 100 lines of code comments to the next developer. 2️⃣ Write for Your Future, Stressed-Out Self. Imagine it's 3 AM, production is on fire, and you haven't touched this service in six months. What would you need to know right now? Write that down. How to run it locally. Key troubleshooting commands. Links to relevant dashboards. Your future self will thank you. 3️⃣ Automate Your Diagrams. Stop screenshotting hand-drawn diagrams and checking them into the repo. They're outdated the moment you commit them. Use text-based diagramming tools like Mermaid.js or PlantUML. You can write them directly in your Markdown files. They are version controlled with your code and always render the latest version. It's a total game-changer. 4️⃣ Create a Consistent Structure. Don't just create random .md files. Agree on a simple folder structure for every service/module. For example: /docs 01_getting_started.md https://lnkd.in/d4bix8Eh 03_runbooks/ rollback_procedure.md Consistency turns a messy folder into a predictable library. 5️⃣ Sync to a Portal. Don't Trap It in the Repo. This is the most critical tip. Your docs are useless if PMs, support, and new hires can't find them without cloning a repo. This doesn't mean you stop writing docs in Git! Use a modern knowledge portal (like Archbee) that automatically syncs with your repository. You get to stay in your IDE, writing in Markdown. Everyone else gets a central, searchable, user-friendly website. It's the best of both worlds. --------------- Docs-as-code isn't just a trend; it's the standard. But making those docs discoverable, structured, and full of context is what separates good engineering teams from great ones. What's your favorite docs-as-code tool or trick? I'm a huge fan of Mermaid.js for diagrams. Your turn. 👇

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

When I started my career in tech, a senior once told me something that has always stayed with me: “In IT, If it isn’t documented , it doesn’t exist” Back then, it sounded dramatic. Today — after multiple projects, rewrites, discussions, and shifting priorities — I know exactly what he meant. Conversations get forgotten. Feature discussions evolve. And verbal agreements… disappear faster than you expect 😬 It’s not about mistrusting people. It’s about creating clarity, continuity, and accountability in a world where teams change, priorities shift, and memory is unreliable. Over the years, here’s what experience has taught me: 👉🏻Document every decision — even a short summary message after a call can protect you months later. 👉🏻Record the “why,” not just the “what.” Context is gold when you revisit old features or debug old logic. 👉🏻Don’t rely on verbal approvals — put it in writing to avoid the classic “I never said that” moment. 👉🏻Keep your notes organized or have proper documentation — future you will thank you when a discussion resurfaces out of nowhere. The funny thing is: documentation doesn’t feel like a “tech skill,” but it’s one of the most underrated trait of a strong engineer. Because in IT, your memory might fail — but your documentation won’t. #softwareengineering #productivity #communication #careeradvice #freshers #sde #jobs

"My code is well-formatted and well-structured. That makes it self-documenting." Your code may not be as self-documenting as you think, even if you follow the best code standards and practices. If you rely on code alone to tell a story, you may still need one thing - context! If you write the code, you've got to support it and documentation is a self-service option to support anyone who will interact with your code. Think about it this way - your comments and documentation are not for you right now. They're for: 🚀 You in the future, when you've had time away from this code and want to jump back in 🚀 Your teammates who will be working on, reviewing, and supporting the code you write 🚀 The new team member who needs to ramp up quickly 🚀 And so many others! Does everything inside your codebase need a comment? Absolutely not, but here are a few good practices you can implement in your development lifecycle if you're not currently doing so. 1️⃣ Write comments that explain 𝘸𝘩𝘺 not just 𝘩𝘰𝘸 2️⃣ Update documentation regularly. Make it part of your PR acceptance criteria where applicable! 3️⃣ Use documentation files like READMEs and wikis 4️⃣ Provide usage examples, FAQs, and pitfalls in your docs