175 lines
4.3 KiB
Markdown
175 lines
4.3 KiB
Markdown
# Documentation Guidelines
|
|
|
|
> How to maintain and extend the `doc/` directory for future AI agents and developers.
|
|
|
|
## Principles
|
|
|
|
1. **Load only what you need.** Each doc is self-contained for its topic. No doc should require reading other docs to be useful.
|
|
2. **One topic per file.** Don't merge unrelated topics. Create a new file instead.
|
|
3. **Keyword-searchable.** Every new doc must be added to `keywords.md`.
|
|
4. **Code examples over prose.** Show the API call, not a paragraph explaining it.
|
|
5. **Keep it current.** When you change code, update the corresponding doc.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
doc/
|
|
├── INDEX.md ← Main entry point (TOC + quick nav)
|
|
├── keywords.md ← Keyword search index (MUST update)
|
|
├── CONTRIBUTING.md ← This file
|
|
├── formats/ ← File format specifications (binary/protocol level)
|
|
├── api/ ← PHP API documentation (how to use the code)
|
|
└── internal/ ← Development notes (learnings, decisions, issues)
|
|
```
|
|
|
|
### When to use which directory
|
|
|
|
| Directory | Content | Example |
|
|
|-----------|---------|---------|
|
|
| `formats/` | Binary file format specs, protobuf structure, encoding details | `pp_song_spec.md`, `pp_playlist_spec.md` |
|
|
| `api/` | PHP class usage, method signatures, code examples | `song.md`, `playlist.md` |
|
|
| `internal/` | Dev notes that help debug or understand history | `learnings.md`, `decisions.md`, `issues.md` |
|
|
|
|
---
|
|
|
|
## Adding a New Document
|
|
|
|
### Step 1: Create the file
|
|
|
|
Place it in the correct directory based on content type (see above).
|
|
|
|
### Step 2: Update INDEX.md
|
|
|
|
Add a line to the Table of Contents section under the appropriate heading:
|
|
|
|
```markdown
|
|
### File Format Specifications
|
|
- [formats/new_format_spec.md](formats/new_format_spec.md) -- Description
|
|
```
|
|
|
|
### Step 3: Update keywords.md
|
|
|
|
Add entries for EVERY searchable keyword in your doc:
|
|
|
|
```markdown
|
|
## New Category
|
|
|
|
| Keyword | Document |
|
|
|---------|----------|
|
|
| keyword1 | [path/to/doc.md](path/to/doc.md) |
|
|
| keyword2 | [path/to/doc.md](path/to/doc.md) Section N |
|
|
```
|
|
|
|
If your keywords fit existing categories, add them there instead.
|
|
|
|
### Step 4: Cross-reference
|
|
|
|
If your doc relates to existing docs, add a "See Also" section at the bottom:
|
|
|
|
```markdown
|
|
## See Also
|
|
|
|
- [Related Doc](../path/to/related.md) -- Why it's related
|
|
```
|
|
|
|
---
|
|
|
|
## Document Template
|
|
|
|
```markdown
|
|
# Title
|
|
|
|
> One-line summary of what this doc covers.
|
|
|
|
## Quick Reference
|
|
|
|
\`\`\`php
|
|
// Most common usage pattern (2-5 lines)
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
## Section 1
|
|
|
|
Content with code examples.
|
|
|
|
---
|
|
|
|
## Section 2
|
|
|
|
More content.
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `path/to/file.php` | What it does |
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [Related Doc](../path/to/related.md)
|
|
```
|
|
|
|
---
|
|
|
|
## Style Guide
|
|
|
|
### Headings
|
|
- `#` for document title (one per file)
|
|
- `##` for main sections
|
|
- `###` for subsections
|
|
- Use `---` horizontal rules between major sections
|
|
|
|
### Code Blocks
|
|
- Always specify language: ` ```php `, ` ```bash `, ` ```markdown `
|
|
- Show complete, runnable examples (not fragments)
|
|
- Include the `use` statements on first occurrence
|
|
|
|
### Tables
|
|
- Use tables for reference data (fields, files, options)
|
|
- Left-align text columns, include header row
|
|
|
|
### Tone
|
|
- Direct. No filler words.
|
|
- "Use X to do Y" not "You can use X to do Y"
|
|
- Show code first, explain after (only if needed)
|
|
|
|
---
|
|
|
|
## Updating Existing Docs
|
|
|
|
When modifying the codebase:
|
|
|
|
1. **New PHP method** → Update the corresponding `api/*.md`
|
|
2. **New file format discovery** → Update `formats/*.md`
|
|
3. **Architecture change** → Update `internal/decisions.md`
|
|
4. **Bug/gotcha found** → Update `internal/issues.md`
|
|
5. **Any change** → Check `keywords.md` for new keywords
|
|
|
|
---
|
|
|
|
## AI Agent Instructions
|
|
|
|
When AGENTS.md tells you to load docs, follow these steps:
|
|
|
|
1. Read `doc/INDEX.md` to understand what's available
|
|
2. Identify which docs match your task (use `keywords.md` if unsure)
|
|
3. Load ONLY the relevant docs
|
|
4. Do NOT load everything -- context window is precious
|
|
|
|
### Loading patterns
|
|
|
|
```
|
|
Task: "Parse a song" → Load: doc/api/song.md
|
|
Task: "Fix protobuf parsing" → Load: doc/formats/pp_song_spec.md
|
|
Task: "Create a playlist" → Load: doc/api/playlist.md
|
|
Task: "Debug ZIP issues" → Load: doc/formats/pp_playlist_spec.md + doc/internal/issues.md
|
|
Task: "Add new feature" → Load: relevant api/ doc + doc/CONTRIBUTING.md
|
|
```
|