Operational Documentation Practice¶
OSKB is the operating manual for Online Services. Documentation is part of completing the work, not a separate project reserved for later.
Core Standard¶
Every meaningful operational discovery should become searchable in OSKB.
Document information when it would help someone maintain, troubleshoot, improve, or understand a system later.
Examples include:
- Where a production setting is managed
- How an integration or synchronization process works
- A deployment or rollback procedure
- Hosting, DNS, Cloudflare, or server configuration
- A recurring problem and its resolution
- Vendor knowledge transferred to Online Services
- A decision that affects future maintenance
- A site-specific exception to a shared standard
Where Documentation Belongs¶
Document information at the narrowest level where it remains useful.
| Discovery | Best location |
|---|---|
| NASPO ValuePoint Salesforce sync frequency | Websites → NASPO → NASPO ValuePoint |
| Shared process for adding servers to Tailscale | Infrastructure |
| NASPO ValuePoint-specific Tailscale details | Websites → NASPO → NASPO ValuePoint |
| Shared Git and deployment workflow | Git & Deployments |
| A site-specific deployment exception | The relevant website section |
| Team documentation expectations | Operations |
| Portfolio-wide maintenance procedure | Websites → Shared Procedures |
| NASPO.org-specific SEO implementation | Websites → NASPO → NASPO.org |
When a site-specific page relies on a shared procedure, link to the shared page and document only the details unique to that site.
Weekly Practice¶
Each Online Services team member should make or review at least one meaningful OSKB improvement each week when operational knowledge has been discovered, changed, or validated.
A meaningful improvement may be:
- A new runbook
- A correction or clarification
- A newly discovered configuration detail
- A troubleshooting note
- A diagram, screenshot, or example that improves an existing procedure
- Validation that an existing procedure is still accurate
The goal is steady reduction of undocumented institutional knowledge, not documentation activity for its own sake.
Review and Publishing¶
OSKB changes may be committed directly to main when that is the agreed repository workflow. Before publishing a substantial structural or procedural update:
- Review the rendered page locally when practical.
- Ask the other Online Services team member to review the content or resulting site.
- Correct any inaccurate, unclear, or duplicated information.
- Keep commits focused and use descriptive commit messages.
Cloudflare Pages automatically publishes changes pushed to the configured production branch.
Temporary Production Changes¶
Temporary production overrides, debugging files, access exceptions, and one-time configuration changes must be removed immediately after the maintenance task is complete. Verification of that cleanup is part of completing the work.
Where practical, document the approved procedure and expected post-maintenance state in the relevant site runbook. Do not leave temporary changes in place for future convenience.
Safety¶
Do not store passwords, private keys, API tokens, authentication secrets, or sensitive security details in OSKB. Document where secrets are managed instead of copying their values into the repository.