Documentation Architecture¶

2025-12-262025-12-31

Status: Informational
Scope: Documentation under .dev/ and docs/
Last Updated: December 31, 2025 19:29:50
Created: December 12, 2025 16:53:42

This document explains the documentation structure of the NeetCode Practice Framework, following software engineering best practices.

📐 Design Principles¶

Separation of Concerns¶

Documentation is organized by target audience, not by file type:

Single Source of Truth¶

Each topic has one authoritative document:

• ❌ Avoid: Same content in multiple places
• ✅ Prefer: One source, with links from other places

Proximity Principle¶

Documentation follows a migration strategy for accessibility:

• Full documentation → docs/tools/ and docs/contributors/ (accessible on website)
• Shortened READMEs → Original locations (tools/README.md, .dev/README.md) with links to full docs
• Code proximity → Tool scripts remain in tools/, tests remain in .dev/

📁 Documentation Structure¶

neetcode/
│
├── README.md                    # 🏠 Project overview (users)
├── README_zh-TW.md              # 🏠 Project overview (繁體中文)
│
├── docs/                        # 📚 Documentation (MkDocs website)
│   ├── index.md                 # Homepage (includes README.md)
│   ├── index_zh-TW.md           # Homepage (繁體中文)
│   │
│   ├── solution-contract.md     # Solution file specification
│   ├── generator-contract.md    # Generator file specification
│   ├── architecture-migration.md # Architecture migration guide
│   ├── github-pages-setup.md    # Deployment guide
│   │
│   ├── patterns/                # Pattern documentation
│   │   ├── README.md
│   │   ├── sliding_window/
│   │   └── two_pointers/
│   │
│   ├── mindmaps/                # Mind map documentation
│   │   ├── index.md
│   │   └── *.md
│   │
│   ├── contributors/            # 👥 Maintainer documentation (website)
│   │   ├── README.md            # Full maintainer guide
│   │   ├── testing.md           # Complete testing documentation
│   │   ├── documentation-architecture.md  # This file
│   │   └── virtual-env-setup.md # Virtual environment setup
│   │
│   ├── tools/                   # 🛠️ Tools documentation (website)
│   │   ├── README.md            # Complete tools reference
│   │   ├── mindmaps/
│   │   │   ├── README.md        # Mind Maps Generator docs
│   │   │   └── ai-markmap-agent/
│   │   │       └── README.md    # AI Markmap Agent docs
│   │   ├── patterndocs/
│   │   │   └── README.md        # Pattern Docs Generator docs
│   │   └── review-code/
│   │       └── README.md        # Review Code tools docs
│   │
│   ├── ontology-design.md       # Ontology design
│   └── mkdocs-content-guide.md  # Content guide
│
├── tools/                       # 🔧 Developer tools (code + scripts)
│   ├── README.md                # Shortened version (links to docs/tools/)
│   ├── mindmaps/                # Mind Maps tools (consolidated)
│   │   ├── core/                # Core module
│   │   ├── ai-markmap-agent/    # AI Markmap Agent
│   │   └── prompts/             # AI prompts
│   ├── patterndocs/             # Pattern Docs Generator
│   ├── review-code/             # Code review tools
│   │   └── validation/          # Validation tools
│   ├── docstring/               # Docstring utilities
│   └── leetcode-api/            # LeetCode API cache
│
└── .dev/                        # 🔒 Maintainer zone (tests + scripts)
    ├── README.md                # Shortened version (links to docs/contributors/)
    ├── tests/                   # Component tests
    └── tests_solutions/         # Solution correctness tests

🎯 Target Audience Guide¶

👤 Users (Learners, Practitioners)¶

What they need: - How to use the framework - Solution and generator specifications - Pattern guides and mind maps

Where to find: - README.md → Quick start - docs/ → Detailed documentation - Website → https://lufftw.github.io/neetcode/

🔧 Contributors (Pull Request Authors)¶

What they need: - Code style and architecture - Tool usage - Testing requirements

Where to find: - docs/tools/README.md → Complete tools reference (website) - docs/contracts/solution-contract.md → Solution format - docs/contributors/testing.md → Complete testing documentation (website)

🛠️ Maintainers (Core Team)¶

What they need: - Internal architecture - Release process - Module deep-dives

Where to find: - docs/contributors/README.md → Full maintainer guide (website) - docs/tools/*/README.md → Complete module documentation (website) - docs/contributors/documentation-architecture.md → Documentation structure (this file)

📋 Documentation Checklist¶

When Adding a New Feature¶

• Update README.md if user-facing
• Update tools/README.md if developer tool
• Add module README if new module
• Update relevant CONTRACT files if API change

When Adding a New Tool¶

• Add to docs/tools/README.md quick reference table (full documentation)
• Add detailed section in docs/tools/README.md
• Create docs/tools/<module>/README.md if complex
• Update tools/README.md (shortened version) if needed
• Add tests to .dev/tests/ or tools/tests/
• Update mkdocs.yml navigation if adding new documentation page

When Modifying Documentation Structure¶

• Update this file (docs/contributors/documentation-architecture.md)
• Update docs/mkdocs-content-guide.md
• Update mkdocs.yml if adding to website
• Update README documentation section
• Verify all links follow the linking strategy (files in docs/ use relative paths, files outside docs/ use GitHub URLs)

🏗️ Industry Best Practices¶

This structure follows patterns from well-known open source projects:

Flask / Django Pattern¶

project/
├── docs/           # Sphinx/MkDocs user documentation
├── scripts/        # Scripts with their own README
└── CONTRIBUTING.md # Contributor guide

Kubernetes Pattern¶

project/
├── docs/           # User documentation
├── hack/           # Developer scripts and tools
└── contributor/    # Contributor documentation

Our Adaptation¶

neetcode/
├── docs/           # User documentation (MkDocs)
├── tools/          # Developer tools (with README.md)
└── .dev/           # Maintainer documentation

❓ FAQ¶

Why migrate documentation to docs/?¶

Migration Strategy: Full documentation has been moved to docs/contributors/ and docs/tools/ to make it accessible via the MkDocs website, while maintaining GitHub browsing context through shortened READMEs in original locations.

Benefits: - ✅ All documentation accessible on MkDocs website - ✅ Maintains GitHub browsing context with shortened READMEs - ✅ Links work correctly in both GitHub and website using relative paths - ✅ Single source of truth for full documentation content

Structure: - docs/contributors/ → Full maintainer documentation (on website) - docs/tools/ → Full tools documentation (on website) - .dev/README.md → Shortened version (links to full docs on website) - tools/README.md → Shortened version (links to full docs on website)

Why .dev/ for maintainer zone?¶

• Clearly signals "internal" directory
• Keeps root directory clean
• Groups with test files (same audience)
• Shortened README maintains GitHub browsing context

Why separate code from documentation in tools/?¶

• tools/ → Contains actual tool scripts (.py files) and shortened README
• docs/tools/ → Contains full documentation (on website)
• Clear separation between code and documentation

How do I know where to add new documentation?¶

Ask: Who is the primary reader?

Note: Original locations (.dev/README.md, tools/README.md) contain shortened versions with links to full documentation on the website.

Link Strategy¶

When adding links in documentation files, follow this strategy:

• ✅ Files inside docs/ directory: Use relative paths (e.g., [README](README.md), [Tools](../tools/README.md))
• ✅ Files outside docs/ directory: Use GitHub absolute URLs (e.g., [Runner](https://github.com/lufftw/neetcode/blob/main/runner/README.md))

This ensures links work correctly in both GitHub repository browsing and the MkDocs website.

Examples: - ✅ docs/contributors/README.md linking to docs/contributors/testing.md → Use [testing.md](testing.md) - ✅ docs/contracts/solution-contract.md linking to runner/README.md → Use [Runner](https://github.com/lufftw/neetcode/blob/main/runner/README.md) - ✅ docs/tools/README.md linking to tools/prompts/README.md → Use [Prompts](https://github.com/lufftw/neetcode/blob/main/tools/prompts/README.md)

📖 See MkDocs Content Guide for detailed linking strategy documentation.

📝 Update Log¶

• 2025-12-24: Migrated maintainer and tools documentation to docs/contributors/ and docs/tools/ for MkDocs website integration. Created shortened READMEs in original locations with links to full documentation.
• 2025-12-24: Added link strategy section documenting rules for linking to files inside/outside docs/ directory
• 2025-12-12: Initial version - Documented architecture after consolidating tools documentation

🔗 Related Documents¶

• Maintainer Guide
• Testing Documentation
• MkDocs Content Guide
• Tools Reference