Skip to content

Commit ca875fa

Browse files
jdaltonjdalton
committed
docs: add comprehensive 3-tier documentation organization guide
- Add documentation-organization.md with complete hierarchy guide - Document tier 1 (monorepo), tier 2 (package), tier 3 (sub-package) structure - Include decision tree, best practices, and migration guide - Add examples from Socket CLI codebase - Link from main docs/README.md for discoverability
1 parent 12cd726 commit ca875fa

File tree

2 files changed

+333
-0
lines changed

2 files changed

+333
-0
lines changed

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## Organization
44

5+
📚 **[Documentation Organization Guide](documentation-organization.md)** - Complete guide to Socket CLI's 3-tier documentation hierarchy
6+
57
- **architecture/** - System design documents and flow diagrams
68
- **build/** - Node.js build system and patching documentation
79
- **configuration/** - Shared configuration architecture

‎docs/documentation-organization.md‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
# Documentation Organization Guide
2+
3+
This guide explains Socket CLI's 3-tier documentation hierarchy and best practices for organizing documentation across the monorepo.
4+
5+
## Overview
6+
7+
Socket CLI follows a structured 3-tier documentation system that separates concerns by scope:
8+
- **Tier 1** (Monorepo) - Cross-package architecture and shared systems
9+
- **Tier 2** (Package) - Package-specific technical documentation
10+
- **Tier 3** (Sub-package) - Implementation-level details for submodules
11+
12+
## 3-Tier Documentation Hierarchy
13+
14+
### Tier 1: Monorepo Documentation (`/docs/`)
15+
16+
**Purpose**: Document cross-package architecture, build systems, development guides, and monorepo-wide standards.
17+
18+
**Structure**:
19+
```
20+
docs/
21+
├── README.md # Complete documentation index
22+
├── architecture/ # System design and flow diagrams
23+
│ ├── cli-architecture.md
24+
│ └── command-patterns.md
25+
├── build/ # Build system documentation
26+
│ ├── build-process.md
27+
│ ├── build-quick-start.md
28+
│ ├── wasm-build-guide.md
29+
│ └── node-patch-creation-guide.md
30+
├── configuration/ # Shared configuration architecture
31+
│ └── env-config.md
32+
├── development/ # Development tools and workflow
33+
│ ├── getting-started.md
34+
│ └── debugging.md
35+
├── guides/ # User-facing how-to guides
36+
│ └── cli-usage.md
37+
├── performance/ # Performance optimization strategies
38+
│ └── optimization-guide.md
39+
├── technical/ # Low-level implementation details
40+
│ └── async-patterns.md
41+
└── testing/ # Testing strategies and guides
42+
└── test-helpers.md
43+
```
44+
45+
**When to Use Tier 1**:
46+
- Documenting systems that span multiple packages
47+
- Architecture decisions affecting the entire monorepo
48+
- Build system documentation (WASM, Node.js patches, etc.)
49+
- Development workflow and tooling
50+
- Cross-package testing strategies
51+
52+
**Examples**:
53+
- `docs/build/wasm-build-guide.md` - WASM compilation affects multiple builder packages
54+
- `docs/architecture/command-patterns.md` - CLI command architecture used across packages/cli
55+
- `docs/testing/test-helpers.md` - Test utilities used across all packages
56+
57+
### Tier 2: Package Documentation (`packages/<pkg>/docs/`)
58+
59+
**Purpose**: Document package-specific APIs, build processes, and implementation details.
60+
61+
**Structure**:
62+
```
63+
packages/<package-name>/docs/
64+
├── README.md # Package documentation index
65+
├── api-reference.md # Public API documentation
66+
├── build-process.md # Package-specific build details
67+
├── upstream-tracking.md # Version tracking for dependencies
68+
└── <implementation>.md # Package-specific technical docs
69+
```
70+
71+
**When to Use Tier 2**:
72+
- Package has complex implementation requiring technical documentation
73+
- Package wraps upstream dependencies needing version tracking
74+
- Package has public APIs requiring reference documentation
75+
- Package has unique build processes not covered in tier 1
76+
77+
**Examples**:
78+
- `packages/yoga-layout/docs/` - Yoga Layout WASM builder documentation
79+
- `README.md` - Package overview with build output specs
80+
- `build-process.md` - Emscripten build configuration and optimization
81+
- `upstream-tracking.md` - Tracking Facebook Yoga v3.1.0 updates
82+
83+
- `packages/onnx-runtime-builder/docs/` - ONNX Runtime WASM builder
84+
- `README.md` - Package overview with required operators list
85+
- `operator-set.md` - 21 operators required for CodeT5 models
86+
- `optimization-strategy.md` - Size optimization techniques
87+
88+
- `packages/minilm-builder/docs/` - ML model conversion pipeline
89+
- `README.md` - 6-phase pipeline overview
90+
- `pipeline-architecture.md` - Conversion process details
91+
- `upstream-tracking.md` - Tracking Hugging Face transformers releases
92+
93+
- `packages/node-sea-builder/docs/` - SEA builder documentation
94+
- `README.md` - SEA build process overview
95+
- `ast-transformations.md` - Code transformations for compatibility
96+
- `verification-process.md` - AST-based verification
97+
98+
### Tier 3: Sub-Package Documentation (`packages/<pkg>/*/docs/`)
99+
100+
**Purpose**: Document language-specific or submodule implementation details.
101+
102+
**Structure**:
103+
```
104+
packages/<package-name>/<submodule>/docs/
105+
├── <implementation-detail>.md
106+
└── <language-specific>.md
107+
```
108+
109+
**When to Use Tier 3**:
110+
- Submodule has complex implementation (e.g., Rust WASM modules)
111+
- Language-specific implementation details (C++, Rust, Python)
112+
- Sub-package has distinct build process from parent package
113+
- Implementation details not relevant to package-level consumers
114+
115+
**Examples**:
116+
- `packages/node-smol-builder/wasm-bundle/docs/` - Rust WASM compression
117+
- `cross-platform-compression.md` - WASM-based compression without UPX
118+
- `macho-compression.md` - macOS-specific Mach-O compression
119+
120+
## Best Practices
121+
122+
### File Naming
123+
- Use lowercase with hyphens: `build-process.md`, `api-reference.md`
124+
- Be descriptive and specific: `wasm-build-guide.md` not `build.md`
125+
- Avoid abbreviations unless widely known: `cli` ✅, `proc` ❌
126+
127+
### Documentation Index Files
128+
Every `docs/` directory MUST have a `README.md` that serves as an index:
129+
- List all documentation files with brief descriptions
130+
- Provide quick links to related documentation
131+
- Include upstream repository links and versions
132+
- Document build output locations and formats
133+
134+
**Example Index Structure**:
135+
```markdown
136+
# package-name Documentation
137+
138+
Package-level documentation for [brief description].
139+
140+
## Overview
141+
142+
[1-2 paragraph overview of what this package does]
143+
144+
## Contents
145+
146+
- **file1.md** - Description of file1
147+
- **file2.md** - Description of file2
148+
149+
## Quick Links
150+
151+
- **Main README**: `../README.md`
152+
- **Build Script**: `../scripts/build.mjs`
153+
154+
## Build Output
155+
156+
- **Location**: `build/output/`
157+
- **Files**: List of output files
158+
159+
## Upstream
160+
161+
- **Repository**: https://github.com/org/repo
162+
- **Version**: vX.Y.Z
163+
- **License**: MIT
164+
```
165+
166+
### Linking Between Tiers
167+
- Use relative paths for cross-tier links
168+
- Link from tier 2 → tier 3: `../wasm-bundle/docs/compression.md`
169+
- Link from tier 3 → tier 2: `../docs/README.md`
170+
- Link from tier 2 → tier 1: `../../docs/build/wasm-build-guide.md`
171+
172+
### Upstream Tracking
173+
For packages wrapping upstream dependencies:
174+
- Always document upstream repository URL
175+
- Document current version being used
176+
- Note license information
177+
- Link to upstream changelog or release notes
178+
- Document update process in `upstream-tracking.md`
179+
180+
### Build Output Documentation
181+
Document build artifacts consistently:
182+
- Artifact locations (`build/`, `dist/`)
183+
- File names and formats
184+
- File sizes (where relevant for performance)
185+
- Platform-specific outputs
186+
187+
### Writing Style
188+
- Be concise and technical - readers are developers
189+
- Use code blocks and examples liberally
190+
- Include diagrams where helpful (ASCII art is fine)
191+
- Focus on "why" not just "what"
192+
- Keep paragraphs short and scannable
193+
194+
## Migration Guide
195+
196+
### Moving Documentation to Correct Tier
197+
198+
**Identify Misplaced Docs**:
199+
1. Cross-package docs in tier 2 → Move to tier 1
200+
2. Implementation-level docs in tier 2 → Move to tier 3
201+
3. Missing package docs → Create tier 2 structure
202+
203+
**Steps to Migrate**:
204+
1. Create target `docs/` directory if needed
205+
2. Move documentation files to correct tier
206+
3. Update internal links to reflect new structure
207+
4. Create or update `README.md` index files
208+
5. Update any references in CLAUDE.md or other guides
209+
210+
**Example Migration**:
211+
```bash
212+
# Bad: Implementation details in package docs
213+
packages/node-smol-builder/docs/cross-platform-compression.md
214+
215+
# Good: Implementation details in sub-package docs
216+
packages/node-smol-builder/wasm-bundle/docs/cross-platform-compression.md
217+
```
218+
219+
## When NOT to Create Documentation
220+
221+
**Avoid over-documentation**:
222+
- Don't document every small utility function
223+
- Don't create docs for simple packages with clear README
224+
- Don't duplicate information from code comments
225+
- Don't create placeholder documentation
226+
227+
**Self-documenting code is better**:
228+
- Simple packages with clear code don't need extensive docs
229+
- Good type definitions and JSDoc comments are often sufficient
230+
- README files may be enough for straightforward packages
231+
232+
## Quick Decision Tree
233+
234+
```
235+
┌─ Cross-package scope?
236+
│ ├─ YES → Tier 1 (/docs/)
237+
│ └─ NO ↓
238+
│
239+
├─ Package-level scope?
240+
│ ├─ YES → Tier 2 (packages/<pkg>/docs/)
241+
│ └─ NO ↓
242+
│
243+
└─ Sub-package/implementation?
244+
└─ YES → Tier 3 (packages/<pkg>/*/docs/)
245+
```
246+
247+
## Examples from Socket CLI
248+
249+
### Well-Organized Documentation
250+
251+
**Tier 1 Example** - `docs/build/wasm-build-guide.md`:
252+
- Covers WASM compilation for ALL builder packages
253+
- Documents shared Emscripten toolchain setup
254+
- Cross-package build strategies
255+
256+
**Tier 2 Example** - `packages/yoga-layout/docs/README.md`:
257+
- Package overview and build output specifications
258+
- Links to sub-documents (build-process, upstream-tracking)
259+
- Quick links to scripts and README
260+
261+
**Tier 3 Example** - `packages/node-smol-builder/wasm-bundle/docs/`:
262+
- Rust-specific WASM implementation details
263+
- Platform-specific compression techniques (Mach-O)
264+
- Not relevant to package-level consumers
265+
266+
### Common Mistakes to Avoid
267+
268+
❌ **Tier Confusion**:
269+
```
270+
# Bad: Cross-package guide in single package
271+
packages/yoga-layout/docs/wasm-compilation-guide.md
272+
273+
# Good: Cross-package guide in tier 1
274+
docs/build/wasm-build-guide.md
275+
```
276+
277+
❌ **Missing Index**:
278+
```
279+
# Bad: No README.md in docs/
280+
packages/onnx-runtime-builder/docs/
281+
├── operators.md
282+
└── optimization.md
283+
284+
# Good: README.md index present
285+
packages/onnx-runtime-builder/docs/
286+
├── README.md
287+
├── operator-set.md
288+
└── optimization-strategy.md
289+
```
290+
291+
❌ **Implementation in Package Docs**:
292+
```
293+
# Bad: Implementation details in tier 2
294+
packages/node-smol-builder/docs/macho-compression.md
295+
296+
# Good: Implementation details in tier 3
297+
packages/node-smol-builder/wasm-bundle/docs/macho-compression.md
298+
```
299+
300+
## Maintenance
301+
302+
### Regular Reviews
303+
- Audit documentation hierarchy quarterly
304+
- Check for outdated upstream version references
305+
- Validate all cross-tier links still work
306+
- Remove obsolete documentation
307+
308+
### Documentation Debt
309+
Track documentation improvements in issues:
310+
- Missing package-level docs
311+
- Outdated version references
312+
- Broken cross-tier links
313+
- Missing index files
314+
315+
### Continuous Improvement
316+
- Add documentation when complexity grows
317+
- Move documentation when scope changes
318+
- Remove documentation when code is simplified
319+
- Keep upstream tracking current
320+
321+
## Resources
322+
323+
- **CLAUDE.md** - Repository Structure & Documentation section
324+
- **Socket Registry CLAUDE.md** - Shared documentation standards
325+
- **Keep a Changelog** - https://keepachangelog.com/
326+
- **Write the Docs** - https://www.writethedocs.org/
327+
328+
---
329+
330+
**Last Updated**: 2025-10-26
331+
**Maintainer**: Socket CLI Team

0 commit comments

Comments
 (0)