From b636a805f9b486ca049e1767b9dee30add52aacd Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Fri, 6 Feb 2026 17:38:56 -0700 Subject: [PATCH] Reduce documentation redundancy while keeping security visible 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 --- .maintenance-notes.md | 116 ++++++++++++++++++++++++++++++++++++++++++ README.md | 14 ++--- 2 files changed, 123 insertions(+), 7 deletions(-) create mode 100644 .maintenance-notes.md diff --git a/.maintenance-notes.md b/.maintenance-notes.md new file mode 100644 index 0000000..055ab5f --- /dev/null +++ b/.maintenance-notes.md @@ -0,0 +1,116 @@ +# 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) diff --git a/README.md b/README.md index c2002ae..2eec161 100644 --- a/README.md +++ b/README.md @@ -131,15 +131,15 @@ See `constitution.md` for an example based on Social.coop's bylaws. - **[SECURITY.md](SECURITY.md)** - Credential management and security best practices - **[constitution.md](constitution.md)** - Example governance constitution -## Security Note +## Security -**Never commit these files** (already in `.gitignore`): -- `config/config.yaml` - Contains your credentials -- `govbot.db` - Your governance database -- `.env` files - Environment variables -- `*.token`, `*.key`, `*.secret` files +⚠️ **Important**: Never commit `config/config.yaml` or other files containing credentials. All sensitive files are automatically protected by `.gitignore`. -See [SECURITY.md](SECURITY.md) for complete security guide. +**See [SECURITY.md](SECURITY.md) for:** +- Complete list of protected files +- Where to store credentials +- Best practices for development and production +- What to do if secrets are accidentally committed ## Development Status