propresenter-php/doc/CONTRIBUTING.md

Documentation Guidelines

How to maintain and extend the doc/ directory.

These rules keep the documentation easy to skim for both humans and AI assistants. For general project contribution rules (issues, PRs, tests), see the top-level README.

Principles

1. Self-contained docs. Each file should be useful on its own. Cross-link generously, but don't force readers to load three other files just to understand one.
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 in the same PR.

---

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:

### 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:

## 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:

## See Also

- [Related Doc](../path/to/related.md) -- Why it's related

---

Document Template

# 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

---

Tips for AI Assistants

The docs are also designed to be easy for AI coding assistants to navigate. The conventions matter:

1. Read INDEX.md first to understand what's available.
2. Identify which docs match your task — keywords.md maps topics to files.
3. Load only the relevant docs; the codebase is large.
4. The Quick Reference section at the top of every API doc is the highest-signal starting point.

Loading patterns

Task	Load
Parse a song	api/song.md
Fix protobuf parsing	formats/pp_song_spec.md
Create a playlist	api/playlist.md
Debug ZIP issues	formats/pp_playlist_spec.md + internal/issues.md
Add a new feature	The relevant api/*.md + this file