Skip to content

Commit b15d03c

Browse files
lufftwlufftw
committed
docs: add documentation architecture guide and restructure tools docs
- Create .dev/DOCUMENTATION_ARCHITECTURE.md explaining best practices - Rewrite tools/README.md in English (was Chinese) - Add "Documentation Guide" section to README.md and README_zh-TW.md - Update .dev/README.md to reference new architecture doc - Fix broken link to FORMAT_CHECKING.md in .dev/README.md Documentation now follows industry best practices: - docs/ for user-facing documentation (published to website) - tools/README.md for developer tools reference - .dev/ for maintainer documentation
1 parent 9e423d5 commit b15d03c

File tree

5 files changed

+426
-153
lines changed

5 files changed

+426
-153
lines changed

‎.dev/DOCUMENTATION_ARCHITECTURE.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Documentation Architecture
2+
3+
This document explains the documentation structure of the NeetCode Practice Framework, following software engineering best practices.
4+
5+
---
6+
7+
## 📐 Design Principles
8+
9+
### Separation of Concerns
10+
11+
Documentation is organized by **target audience**, not by file type:
12+
13+
| Directory | Purpose | Target Audience |
14+
|-----------|---------|-----------------|
15+
| `docs/` | User-facing documentation | Users, learners |
16+
| `tools/README.md` | Developer tools reference | Contributors |
17+
| `tools/*/README.md` | Module technical details | Deep contributors |
18+
| `.dev/` | Maintainer documentation | Maintainers |
19+
20+
### Single Source of Truth
21+
22+
Each topic has **one authoritative document**:
23+
24+
- ❌ Avoid: Same content in multiple places
25+
- ✅ Prefer: One source, with links from other places
26+
27+
### Proximity Principle
28+
29+
Documentation lives **close to the code** it describes:
30+
31+
- Tool documentation → `tools/README.md`
32+
- Module documentation → `tools/<module>/README.md`
33+
- Test documentation → `.dev/TESTING.md`
34+
35+
---
36+
37+
## 📁 Documentation Structure
38+
39+
```
40+
neetcode/
41+
│
42+
├── README.md # 🏠 Project overview (users)
43+
├── README_zh-TW.md # 🏠 Project overview (繁體中文)
44+
│
45+
├── docs/ # 📚 User documentation (MkDocs website)
46+
│ ├── index.md # Homepage (includes README.md)
47+
│ ├── index_zh-TW.md # Homepage (繁體中文)
48+
│ │
49+
│ ├── SOLUTION_CONTRACT.md # Solution file specification
50+
│ ├── GENERATOR_CONTRACT.md # Generator file specification
51+
│ ├── ARCHITECTURE_MIGRATION.md # Architecture migration guide
52+
│ ├── GITHUB_PAGES_SETUP.md # Deployment guide
53+
│ │
54+
│ ├── patterns/ # Pattern documentation
55+
│ │ ├── README.md
56+
│ │ ├── sliding_window.md
57+
│ │ └── two_pointers.md
58+
│ │
59+
│ ├── mindmaps/ # Mind map documentation
60+
│ │ ├── index.md
61+
│ │ └── *.md
62+
│ │
63+
│ ├── ONTOLOGY_DESIGN.md # Ontology design (not in nav)
64+
│ └── MKDOCS_CONTENT_GUIDE.md # Content guide (not in nav)
65+
│
66+
├── tools/ # 🔧 Developer tools
67+
│ ├── README.md # Tools reference (comprehensive)
68+
│ │
69+
│ ├── mindmaps/
70+
│ │ └── README.md # Mind map module technical docs
71+
│ │
72+
│ ├── patterndocs/
73+
│ │ └── README.md # Pattern docs module technical docs
74+
│ │
75+
│ └── prompts/
76+
│ └── README.md # AI prompts documentation
77+
│
78+
└── .dev/ # 🔒 Maintainer documentation
79+
├── README.md # Maintainer guide
80+
├── TESTING.md # Testing documentation
81+
├── VIRTUAL_ENV_SETUP.md # Virtual environment guide
82+
└── DOCUMENTATION_ARCHITECTURE.md # This file
83+
```
84+
85+
---
86+
87+
## 🎯 Target Audience Guide
88+
89+
### 👤 Users (Learners, Practitioners)
90+
91+
**What they need:**
92+
- How to use the framework
93+
- Solution and generator specifications
94+
- Pattern guides and mind maps
95+
96+
**Where to find:**
97+
- `README.md` → Quick start
98+
- `docs/` → Detailed documentation
99+
- Website → `https://lufftw.github.io/neetcode/`
100+
101+
### 🔧 Contributors (Pull Request Authors)
102+
103+
**What they need:**
104+
- Code style and architecture
105+
- Tool usage
106+
- Testing requirements
107+
108+
**Where to find:**
109+
- `tools/README.md` → Tools reference
110+
- `docs/SOLUTION_CONTRACT.md` → Solution format
111+
- `.dev/TESTING.md` → Test requirements
112+
113+
### 🛠️ Maintainers (Core Team)
114+
115+
**What they need:**
116+
- Internal architecture
117+
- Release process
118+
- Module deep-dives
119+
120+
**Where to find:**
121+
- `.dev/README.md` → Maintainer guide
122+
- `tools/*/README.md` → Module details
123+
- `.dev/DOCUMENTATION_ARCHITECTURE.md` → This file
124+
125+
---
126+
127+
## 📋 Documentation Checklist
128+
129+
### When Adding a New Feature
130+
131+
- [ ] Update `README.md` if user-facing
132+
- [ ] Update `tools/README.md` if developer tool
133+
- [ ] Add module README if new module
134+
- [ ] Update relevant CONTRACT files if API change
135+
136+
### When Adding a New Tool
137+
138+
- [ ] Add to `tools/README.md` quick reference table
139+
- [ ] Add detailed section in `tools/README.md`
140+
- [ ] Create `tools/<module>/README.md` if complex
141+
- [ ] Add tests to `.dev/tests/` or `tools/tests/`
142+
143+
### When Modifying Documentation Structure
144+
145+
- [ ] Update this file (`DOCUMENTATION_ARCHITECTURE.md`)
146+
- [ ] Update `docs/MKDOCS_CONTENT_GUIDE.md`
147+
- [ ] Update `mkdocs.yml` if adding to website
148+
- [ ] Update README documentation section
149+
150+
---
151+
152+
## 🏗️ Industry Best Practices
153+
154+
This structure follows patterns from well-known open source projects:
155+
156+
### Flask / Django Pattern
157+
158+
```
159+
project/
160+
├── docs/ # Sphinx/MkDocs user documentation
161+
├── scripts/ # Scripts with their own README
162+
└── CONTRIBUTING.md # Contributor guide
163+
```
164+
165+
### Kubernetes Pattern
166+
167+
```
168+
project/
169+
├── docs/ # User documentation
170+
├── hack/ # Developer scripts and tools
171+
└── contributor/ # Contributor documentation
172+
```
173+
174+
### Our Adaptation
175+
176+
```
177+
neetcode/
178+
├── docs/ # User documentation (MkDocs)
179+
├── tools/ # Developer tools (with README.md)
180+
└── .dev/ # Maintainer documentation
181+
```
182+
183+
---
184+
185+
## ❓ FAQ
186+
187+
### Why separate `docs/` from `tools/`?
188+
189+
- `docs/` → Published to website, user-facing
190+
- `tools/` → GitHub-only, developer-facing
191+
192+
Different audiences, different update cycles, different review requirements.
193+
194+
### Why `.dev/` for maintainer docs?
195+
196+
- Clearly signals "internal" documentation
197+
- Keeps root directory clean
198+
- Groups with test files (same audience)
199+
200+
### Why not put everything in `docs/`?
201+
202+
- MkDocs publishes everything in `docs/` to the website
203+
- Internal documentation shouldn't be public-facing
204+
- Separation allows different access controls
205+
206+
### How do I know where to add new documentation?
207+
208+
Ask: **Who is the primary reader?**
209+
210+
| Reader | Location |
211+
|--------|----------|
212+
| User learning the framework | `docs/` |
213+
| Contributor adding features | `tools/README.md` |
214+
| Maintainer debugging issues | `.dev/` |
215+
216+
---
217+
218+
## 📝 Update Log
219+
220+
- **2025-12-12**: Initial version - Documented architecture after consolidating tools documentation
221+
222+
---
223+
224+
## 🔗 Related Documents
225+
226+
- [Maintainer Guide](.dev/README.md)
227+
- [Testing Documentation](.dev/TESTING.md)
228+
- [MkDocs Content Guide](docs/MKDOCS_CONTENT_GUIDE.md)
229+
- [Tools Reference](tools/README.md)
230+

‎.dev/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,10 @@ tools/run_format_tests.sh
136136
|----------|-------------|
137137
| [TESTING.md](TESTING.md) | Complete testing documentation (strategy, principles, workflow) |
138138
| [VIRTUAL_ENV_SETUP.md](VIRTUAL_ENV_SETUP.md) | Virtual environment setup guide |
139+
| [DOCUMENTATION_ARCHITECTURE.md](DOCUMENTATION_ARCHITECTURE.md) | Documentation structure and best practices |
139140
| [tests/README.md](tests/README.md) | Component tests detailed description |
140141
| [tests_solutions/README.md](tests_solutions/README.md) | Solution tests detailed description |
141-
| [../tools/FORMAT_CHECKING.md](../tools/FORMAT_CHECKING.md) | Format checking tools description |
142+
| [../tools/README.md](../tools/README.md) | Developer tools reference |
142143

143144
---
144145

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -887,6 +887,27 @@ neetcode/
887887

888888
> **📝 Note:** Files in `docs/mindmaps/`, `docs/patterns/`, and `docs/pages/` are auto-generated. Edit the source files in `ontology/`, `meta/`, and `tools/` instead.
889889
890+
### Documentation Guide
891+
892+
Documentation is organized by **target audience**:
893+
894+
| Location | Purpose | Audience |
895+
|:---------|:--------|:---------|
896+
| `docs/` | User documentation (published to website) | ✅ Users |
897+
| `tools/README.md` | Developer tools reference | 🔧 Contributors |
898+
| `tools/*/README.md` | Module technical details | 🔧 Contributors |
899+
| `.dev/` | Maintainer documentation | 🔧 Maintainers |
900+
901+
**Key Documentation Files:**
902+
903+
| Document | Description |
904+
|:---------|:------------|
905+
| [`docs/SOLUTION_CONTRACT.md`](docs/SOLUTION_CONTRACT.md) | Solution file specification |
906+
| [`docs/GENERATOR_CONTRACT.md`](docs/GENERATOR_CONTRACT.md) | Generator file specification |
907+
| [`tools/README.md`](tools/README.md) | Complete tools reference |
908+
| [`.dev/README.md`](.dev/README.md) | Maintainer guide |
909+
| [`.dev/DOCUMENTATION_ARCHITECTURE.md`](.dev/DOCUMENTATION_ARCHITECTURE.md) | Documentation structure |
910+
890911
---
891912

892913
## ❓ Frequently Asked Questions

‎README_zh-TW.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -862,6 +862,27 @@ neetcode/
862862

863863
> **📝 注意：** `docs/mindmaps/`、`docs/patterns/`、`docs/pages/` 中的檔案都是自動生成的。請編輯 `ontology/`、`meta/`、`tools/` 中的來源檔案。
864864
865+
### 文件指南
866+
867+
文件依**目標讀者**組織：
868+
869+
| 位置 | 用途 | 對象 |
870+
|:-----|:-----|:-----|
871+
| `docs/` | 使用者文件（發布到網站） | ✅ 使用者 |
872+
| `tools/README.md` | 開發者工具參考 | 🔧 貢獻者 |
873+
| `tools/*/README.md` | 模組技術細節 | 🔧 貢獻者 |
874+
| `.dev/` | 維護者文件 | 🔧 維護者 |
875+
876+
**主要文件：**
877+
878+
| 文件 | 說明 |
879+
|:-----|:-----|
880+
| [`docs/SOLUTION_CONTRACT.md`](docs/SOLUTION_CONTRACT.md) | 解答檔案規格 |
881+
| [`docs/GENERATOR_CONTRACT.md`](docs/GENERATOR_CONTRACT.md) | 生成器檔案規格 |
882+
| [`tools/README.md`](tools/README.md) | 完整工具參考 |
883+
| [`.dev/README.md`](.dev/README.md) | 維護者指南 |
884+
| [`.dev/DOCUMENTATION_ARCHITECTURE.md`](.dev/DOCUMENTATION_ARCHITECTURE.md) | 文件架構說明 |
885+
865886
---
866887

867888
## ❓ 常見問題

0 commit comments

Comments
 (0)