PSP-001: Living Documentation Policy
Status: Proposed
Author: Dustin M. Gelegonya, Claude (AI)
Created: December 2025
Updated: December 2025
Authority: PSP v1
1. Identifier & Title
PSP-001: Living Documentation Policy
2. Problem Statement
JellyLabs maintains two categories of material:
- Specifications — Immutable, versioned protocols (DIDP, PPP, PSP)
- Documentation — Explanatory material that supports specifications
Without a clear policy, documentation risks either:
- Becoming stale (if updates are too burdensome)
- Drifting from specifications (if updates are too casual)
3. Proposed Change
Establish a Living Documentation Policy that:
- Defines three tiers of material (Protocol Specification, Governance Document, Explanatory Documentation)
- Permits explanatory documentation to evolve without PSP proposals
- Requires visible “Living Document” notices and last-updated dates
- Mandates changelogs for documents with significant update history
- Defines escalation criteria for when a PSP proposal is required
4. Rationale
This approach balances:
- Freshness — Documentation can improve continuously
- Stability — Specifications remain authoritative and immutable
- Transparency — Changes are visible via dates and changelogs
- Governance — Significant changes still require formal review
The three-tier classification provides clear escalation paths.
5. Alternatives Considered
Alternative A: Require PSP for all documentation changes
Rejected because: Would create excessive overhead for minor clarifications, leading to stale documentation.
Alternative B: Allow unrestricted documentation changes
Rejected because: Risk of documentation drifting from specifications without visibility.
6. Impact Analysis
Effects on Specifications
None. Specifications remain immutable after publication.
Effects on Documentation
- All explanatory docs must include “Living Document” notice
- All docs must display last-updated date
- High-traffic docs should maintain changelogs
Effects on Contributors
- Lower barrier for documentation improvements
- Clear criteria for when PSP is required
- Reduced risk of accidental normative drift
7. Risks and Mitigations
| Risk | Mitigation |
|---|---|
| Documentation contradicts specifications | Escalation criteria require PSP for normative changes |
| Changes become invisible | Required notices and dates ensure visibility |
| Changelog overhead | Changelogs only required for substantive changes |
8. Decision Status
- Status: Proposed
- Decision Authority: Protocol Steward (Dustin M. Gelegonya)
- Decision Date: Pending
References
- PSP v1 — Proposal Specification Protocol
- Specs vs Docs — Material classification
- DIDP v1 — Development protocol
- PPP v1 — Publication protocol