A design exists in two forms: the design-in-your-head and the design-on-paper. The first is rich with context, reasoning, and nuance. The second is what survives after you've moved to other projects, left the company, or simply forgotten the details.

The gap between these two forms is where projects fail. Brilliant designs become incomprehensible systems when the reasoning behind them is lost. Future maintainers make changes that violate assumptions they never knew existed. What seemed like a robust architecture becomes a fragile mess because no one remembers why things were built this way.

This page teaches you to bridge that gap—to produce documentation that captures not just what your design is, but why it is that way, preserving the insight and reasoning that made it successful.

Before creating documentation, understand who will read it and why. Different audiences have different needs, and effective documentation addresses all of them.

The Core Audiences:

The Useful Lifespan of Documentation:

Different parts of your documentation have different lifespans:

• High-level architecture: Years. Changes slowly as the fundamental approach remains stable.
• Module relationships: Months to years. Evolves as the system grows.
• Class details: Weeks to months. May change frequently during active development.
• Specific implementation notes: Days to weeks. Often replaced by code comments.

Understanding these lifespans helps you invest appropriately. Spend more effort on documentation that will remain relevant; accept that detailed implementation docs will need updates.

Comprehensive design documentation includes several components. Not every design needs all of these, but knowing the full toolkit helps you choose what's appropriate.

Component 1: Executive Summary / Overview

A high-level description that anyone can understand in 2-3 minutes. This is often the only part that executives, product managers, or engineers from other teams will read.

Component 2: Architecture Diagram(s)

Visual representations of the design at appropriate levels of abstraction. Diagrams are often the first thing people look for.

Essential diagrams for LLD:

• Class diagram: Shows entities, their attributes, methods, and relationships
• Sequence diagram(s): Shows key flows through the system
• State diagram (if applicable): Shows lifecycle states and transitions

Diagram quality guidelines:

• Use consistent notation (UML is the standard, but consistency matters more than strict compliance)
• Include a legend if using non-standard symbols
• Keep diagrams focused—multiple small diagrams are better than one overwhelming diagram
• Update diagrams when the design changes (or delete them if not updated)

Component 3: Entity/Class Specifications

Detailed descriptions of each significant class/entity. This goes beyond what's visible in a diagram.

Component 4: Key Flows / Sequence Documentation

Narrative description of how major operations work, complementing sequence diagrams.

Beyond describing what the design is, capture why it's that way. This is what distinguishes documentation that enables future success from documentation that merely records the present.

Component 5: Architecture Decision Records (ADRs)

We introduced ADRs in the previous page on trade-offs. Including them in your final documentation package provides crucial context for significant decisions.

Component 6: Assumptions and Constraints

Every design is built on assumptions. Document them explicitly so future readers can assess whether they still hold.

Component 7: Known Limitations and Future Considerations

No design is perfect. Document what you know isn't ideal and what might need to change.

Even complete documentation fails if it's not clear. Writing clarity is a skill that improves with practice and attention.

Principle 1: Write for the Confused Reader

Assume your reader is intelligent but unfamiliar with your context. They don't know what you know. Write as if explaining to a smart colleague who just joined the team.

Practical techniques:

• Define terms before using them
• Use consistent naming throughout (don't switch between "order" and "purchase request")
• Explain acronyms on first use
• Link to external concepts rather than assuming knowledge

Principle 2: Structure for Scanning

Most readers won't read linearly. They'll scan for the section they need. Structure your document accordingly:

• Use clear, descriptive headings
• Start sections with summary/context before details
• Use tables for comparison or structured information
• Use lists for enumerated points
• Use callouts/boxes for important warnings or tips

Principle 3: Prefer Concrete Over Abstract

Abstract descriptions are hard to understand. Concrete examples make concepts tangible.

Instead of:

"The system validates inputs according to configured rules."

Write:

"The system validates inputs using the ValidatorChain. For orders, this checks that items are in stock, customer is not blacklisted, and payment method is supported. Example: An order with an out-of-stock item returns a ValidationError listing the unavailable items."

Principle 4: Show, Don't Just Tell

Code examples, diagrams, and worked scenarios communicate more effectively than prose alone.

Documentation that isn't maintained becomes actively harmful. Outdated docs lead developers astray, causing them to build on false assumptions. Here's how to keep docs useful over time.

Strategy 1: Locate Documentation Near Code

Documentation maintained separately from code tends to drift. Keep documentation as close to the code as practical:

• API documentation in code comments (e.g., JSDoc, Javadoc)
• Module overviews in README.md files within the module
• Design docs in a /docs folder within the repository
• ADRs in a /docs/adr folder

When documentation lives with code, it's more likely to be noticed during code changes.

Strategy 2: Define Documentation Ownership

Someone needs to be responsible for documentation accuracy. Options:

• The original author is responsible for updates
• The team collectively owns documentation (anyone changing code updates docs)
• A designated documentation steward reviews periodically

Without ownership, documentation degrades by default.

Strategy 3: Include Documentation in Definition of Done

If documentation is optional, it will be skipped when deadlines press. Build it into your team's workflow:

• PR template includes "Documentation updated?" checkbox
• Code review includes documentation review
• Significant features aren't complete until documented

Strategy 4: Prefer Evergreen Content

Some content ages better than others. Prioritize documentation that remains accurate longer:

• Evergreen: Why decisions were made, overall architecture, core concepts
• Volatile: Specific method signatures, detailed class lists, step-by-step procedures

For volatile content, consider generating it from code (e.g., API docs from annotations) rather than maintaining it manually.

Strategy 5: Delete Rather Than Neglect

If documentation can't be maintained, delete it. Outdated documentation is worse than no documentation because it misleads without warning. A clean, smaller set of accurate docs is more valuable than comprehensive but unreliable docs.

In LLD interviews, you won't produce formal documentation, but the principles of good documentation apply to how you present your design.

Whiteboard/Drawing Equivalent of Documentation:

Articulation Quality Matters:

Interviewers assess not just your design but how clearly you can explain it. This is a proxy for how well you'd communicate with teammates.

Good practices:

• Introduce before diving in: "Let me start with the core entities..."
• Label everything you draw
• Explain relationships, don't just draw lines
• Summarize after each section: "So that's the core domain model. Any questions before I move to the flows?"
• Invite interaction: "Does this make sense so far?"

What Interviewers Notice:

Finally, a brief survey of tools and formats for creating LLD documentation. Choose tools your team will actually use.

For Diagrams:

For Written Documentation:

Recommended Approach:

For most teams, a combination works well:

1. Markdown in repo for technical design docs, ADRs, and module READMEs
2. Diagrams-as-code (Mermaid or PlantUML) for maintainability
3. Code comments for public API documentation
4. Wiki/Confluence for operational docs and cross-team communication

The key is that docs should be where developers look. If your team lives in GitHub, docs should be in GitHub. If your team uses Confluence daily, put docs there.

Documentation bridges the gap between the design in your head and the design that survives your involvement. Let's consolidate the key insights:

Module Complete:

With this page, we've completed Module 7: Iterating and Refining. You've learned that design is inherently iterative, how to gather and incorporate feedback, how to make trade-off decisions with confidence, and how to document your final design for implementation and future maintenance.

These skills transform you from someone who creates designs into someone who creates lasting designs—designs that can be understood, maintained, and evolved by the team over time.