Glossary
By the Glue Team
Codebase documentation is written explanation of how software is built, structured, and functions. It includes architecture guides, API documentation, decision records, setup instructions, and deployment guides. Good codebase documentation makes the code self-explaining, reduces onboarding time, and enables confident maintenance.
Codebase documentation covers:
Documentation quality directly impacts team velocity:
Onboarding Speed: With documentation, new developers become productive in days. Without it, weeks. A new developer can read architecture documentation and understand the system. Without it, they're blocked on tribal knowledge from experts.
Reduces Bus Factor: Undocumented knowledge is trapped in people's heads. Documented knowledge is shared. If the expert leaves, knowledge remains.
Enables Refactoring: You can't safely refactor code if you don't understand why it's structured that way. Decision records explain the reasoning. Refactoring becomes safer.
Faster Reviews: Code reviews are more efficient when context is documented. Reviewer understands intent instead of guessing. Feedback is more on-target.
Knowledge Sharing: Different learning styles exist. Some prefer reading code, others prefer prose explanation. Documentation serves the second group, making knowledge accessible to more people.
Retention of Knowledge: Memory is fallible. "Why did we choose this library?" becomes a mystery in two years. Decision records are permanent.
Attracts Talent: Developers want to work with well-documented codebases. It's a signal of professionalism and engineering excellence.
Architecture Diagrams: Visual representation of system structure. Boxes for services/modules, arrows for communication. Essential for understanding how components relate.
README Files: Usually in project root. What is this project? How do you run it? Links to detailed docs. First stop for understanding a codebase.
API Documentation: If you build APIs, document them. What endpoints exist, what they do, what parameters they need, what they return. Swagger/OpenAPI is standard.
Code Comments: Inline comments explaining tricky logic. Not every line needs comments, but non-obvious parts should. Explain WHY, not WHAT (code shows what).
Decision Records (ADRs): Document major decisions: "We chose PostgreSQL over MongoDB because..." Captures reasoning that disappears when decision-makers leave.
Setup Guides: Step-by-step how to set up development environment. Automate where possible (setup scripts), document where not.
Deployment Guides: How production deployment works. How rollbacks work. How to emergency-patch. How monitoring and alerting work.
Runbooks: Step-by-step procedures for common tasks. How to add a new feature, how to handle incidents, how to release.
FAQs: Common questions and answers. "How do I add a new payment method?" "Why does this test fail intermittently?"
Outdated Documentation: Docs written then forgotten. Code changes but docs don't. New developer follows docs, hits dead ends, loses trust in documentation.
Over-Detailed Documentation: Pages describing every class and function. Too much information becomes noise. Good documentation is high-level, specific where it matters.
Wrong Level of Detail: Documentation assuming expertise that doesn't exist. "Install and run" without explaining where to install or how to run.
Scattered Documentation: Architecture in wiki, APIs in README, decisions in old Slack messages. No single source of truth. Impossible to keep current.
No Owner: Documentation that belongs to everyone belongs to no one. Establish ownership so someone cares about accuracy.
Written by Non-Authors: People unfamiliar with code writing documentation make mistakes. Writers should be engineers familiar with systems.
Start with Architecture: Document the big picture first. How many services? What does each do? How do they communicate? Then document details.
Explain WHY, Not WHAT: Code shows what it does. Documentation explains why decisions were made. Why this library? Why this pattern? Why this structure?
Assume Little Knowledge: Don't assume readers know your domain, your architecture, your stack. Explain from first principles.
Include Examples: A concrete example clarifies better than abstract explanation. "Here's how you add a new payment method" is clearer than "payment methods are pluggable."
Keep Current: Docs decay. Include doc updates in definition of done. When code changes, update docs. Schedule quarterly doc reviews.
Link Intelligently: Cross-link related documentation. Documentation is web of interconnected knowledge, not linear book.
Use Visuals: Diagrams, screenshots, flow charts. Complex ideas become clear with visuals.
Establish Standards: Consistent style and organization makes navigation easier. New docs follow existing patterns.
Glue helps with codebase documentation by making code structure visible. Instead of manually writing "service X calls service Y," code intelligence reveals this. Instead of manually documenting what a module does, you can describe intent and let code show implementation.
"Good developers don't need documentation." False. Good developers appreciate good documentation—it saves time. Great developers write documentation because they understand its value.
"Code is self-documenting." Partly true. Good code is readable. But it can't document why decisions were made or provide context. Code explains what; documentation explains why and how.
"We don't have time to document." You don't have time NOT to. Time spent documenting is recovered 10x in reduced onboarding, fewer misunderstandings, and faster decisions.
"Documentation is support's job." Partly false. User-facing documentation is support's responsibility. Codebase documentation is engineering's responsibility.
Code Health: Well-documented code is healthier. Documentation is one dimension of code health.
Developer Onboarding: Documentation accelerates onboarding. Good documentation reduces dependency on mentors.
Knowledge Silos: Undocumented knowledge creates silos. Documentation breaks them.
API Documentation: Specific type of codebase documentation focused on public APIs.
Q: How much documentation is enough? A: Enough that a new developer can understand the system and contribute without constant help. Can they answer "What does service X do?", "How do I deploy?", "Why did we choose this library?" from documentation? If yes, that's enough.
Q: Who should write codebase documentation? A: Engineers who built the system. They understand rationale, trade-offs, and gotchas. Documentation is better reviewed by different engineers (catches missing context) but written by authors.
Q: Should documentation be in code or separate? A: Both. High-level architecture and decisions are separate (wiki, markdown). Inline comments for tricky logic. APIs are documented both in code (docstrings) and in separate guides. Use both.
Q: How do you keep documentation updated? A: Make updates part of development workflow. When code changes, update docs. Code review should check docs. Schedule quarterly doc audits to catch drift.
Keep reading
