b636a805f9
Applied "Single Source of Truth with Contextual Pointers" pattern: README.md changes: - Simplified "Security Note" section to brief warning + bullets - Removed detailed file list (now only in SECURITY.md) - Kept inline warning in Quick Start (contextual, at point of use) - Added bullets describing what SECURITY.md covers - Result: Brief, clear, points to authoritative source Documentation strategy: - SECURITY.md = single source of truth (all details) - Other docs = brief inline warnings + links to SECURITY.md - Inline warnings kept at critical moments (e.g., creating config.yaml) - Platform-specific notes stay in platform guides Added .maintenance-notes.md: - Documents the documentation strategy - Explains what goes where and why - Provides guidance for future updates - Helps prevent redundancy creep Benefits: - Easier to maintain (update SECURITY.md, others just link) - Still highly visible (warnings at critical steps) - No loss of information (everything in SECURITY.md) - Clear ownership (each file owns specific info) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
117 lines
4.1 KiB
Markdown
117 lines
4.1 KiB
Markdown
# Documentation Maintenance Notes
|
|
|
|
## Documentation Strategy
|
|
|
|
We follow a **"Single Source of Truth with Contextual Pointers"** pattern to minimize redundancy while keeping security visible.
|
|
|
|
### Pattern
|
|
|
|
```
|
|
README.md: Brief inline warnings → Link to SECURITY.md
|
|
QUICKSTART.md: Brief inline warnings → Link to SECURITY.md
|
|
MASTODON_SETUP: Platform-specific notes → Link to SECURITY.md
|
|
SECURITY.md: ← SINGLE SOURCE OF TRUTH (all details)
|
|
```
|
|
|
|
### What Goes Where
|
|
|
|
**SECURITY.md** (single source of truth):
|
|
- Complete list of all protected files
|
|
- Detailed explanations of where secrets are stored
|
|
- Best practices for development and production
|
|
- What to do if secrets are accidentally committed
|
|
- Pre-commit hooks and scripts
|
|
- Security audit checklist
|
|
- All the "how" and "why" details
|
|
|
|
**README.md** (overview):
|
|
- Brief security warning in Quick Start (inline, at point of use)
|
|
- Security section: short warning + bullet list of what SECURITY.md covers
|
|
- Links to SECURITY.md for details
|
|
- NO detailed file lists (that's in SECURITY.md)
|
|
|
|
**QUICKSTART.md** (hands-on guide):
|
|
- Security warning box when copying config.yaml (critical moment)
|
|
- Link to SECURITY.md
|
|
- Brief contextual notes (e.g., "API keys go in ~/.llm/keys.json")
|
|
|
|
**MASTODON_SETUP.md** (platform-specific):
|
|
- Prominent link to SECURITY.md at top of security section
|
|
- Mastodon-specific security notes (OAuth files, scopes, etc.)
|
|
- Link to SECURITY.md for general best practices
|
|
|
|
### What's NOT Redundant (Keep It)
|
|
|
|
✅ **Inline security warnings at critical steps** (QUICKSTART when creating config)
|
|
✅ **Brief reminders in context** (README: "config.yaml is gitignored")
|
|
✅ **Platform-specific notes** (MASTODON_SETUP: Mastodon OAuth files)
|
|
✅ **Links to SECURITY.md** (everywhere - that's the point!)
|
|
|
|
### What IS Redundant (Removed)
|
|
|
|
❌ Detailed file lists in multiple places → Only in SECURITY.md
|
|
❌ Lengthy explanations of .gitignore → Only in SECURITY.md
|
|
❌ Duplicate best practices → Only in SECURITY.md
|
|
|
|
## Updating Documentation
|
|
|
|
### If You Change Something Security-Related
|
|
|
|
1. **Update SECURITY.md first** (it's the source of truth)
|
|
2. **Check if inline warnings need updates** (usually they don't, unless big change)
|
|
3. **Don't duplicate details** - just ensure links to SECURITY.md are present
|
|
|
|
### Examples
|
|
|
|
**Adding a new protected file pattern:**
|
|
- ✅ Add to .gitignore
|
|
- ✅ Document in SECURITY.md (protected files section)
|
|
- ✅ Test the pattern
|
|
- ❌ Don't add to README or QUICKSTART (they link to SECURITY.md)
|
|
|
|
**Changing where secrets are stored:**
|
|
- ✅ Update SECURITY.md (detailed explanation)
|
|
- ✅ Update inline context if needed (e.g., QUICKSTART: "edit config.yaml")
|
|
- ❌ Don't duplicate the explanation everywhere
|
|
|
|
**Adding a new platform:**
|
|
- ✅ Create platform-specific setup guide (like MASTODON_SETUP.md)
|
|
- ✅ Link to SECURITY.md at top of security section
|
|
- ✅ Add platform-specific security notes
|
|
- ❌ Don't duplicate general security advice
|
|
|
|
## Testing for Redundancy
|
|
|
|
Before committing docs, check:
|
|
|
|
```bash
|
|
# Find where a term appears
|
|
grep -n "config.yaml" README.md QUICKSTART.md MASTODON_SETUP.md SECURITY.md
|
|
|
|
# Are the mentions:
|
|
# - Contextual/inline warnings? → OK
|
|
# - Links to SECURITY.md? → OK
|
|
# - Detailed duplicate explanations? → REMOVE
|
|
```
|
|
|
|
## File Ownership
|
|
|
|
| File | Owns This Information |
|
|
|------|----------------------|
|
|
| SECURITY.md | Complete security guidance, file lists, best practices |
|
|
| README.md | High-level overview, links to details |
|
|
| QUICKSTART.md | Step-by-step with inline warnings |
|
|
| MASTODON_SETUP.md | Mastodon-specific security |
|
|
| PLATFORMS.md | Platform implementation (references SECURITY.md) |
|
|
|
|
## Current State (Post-Consolidation)
|
|
|
|
✅ README.md: Simplified "Security" section to brief warning + bullets about what's in SECURITY.md
|
|
✅ QUICKSTART.md: Contextual warning at critical moment
|
|
✅ MASTODON_SETUP.md: Platform-specific notes + link to SECURITY.md
|
|
✅ SECURITY.md: Complete authoritative guide
|
|
|
|
Redundancy: Minimal (only intentional inline warnings)
|
|
Maintenance: Easy (update SECURITY.md, others just link)
|
|
Visibility: High (warnings at critical steps)
|