📄 Documentation Contribution & Maintenance Guidelines
This document defines how documentation is written, reviewed, and kept current.
Ownership assignments live in ownership/documentation-owners.md.
Roles
| Role | Responsibility |
|---|---|
| Author | Drafts or updates the document |
| Owner | Accountable for long-term accuracy — assigned in ownership/documentation-owners.md |
| Reviewer | The Owner's supervisor by default, otherwise a contributor designated by the owner |
Every document must have a named Owner assigned in ownership/documentation-owners.md. Docs without an Owner are candidates for archival or removal.
Contributing
-
Documentation should live as close to its subject as possible:
- In the relevant repo — e.g. oev-searcher docs in the oev-searcher repo, airseeker docs in the airseeker repo
- In
internal-operations/— for cross-cutting processes, team operations, or anything not tied to a specific codebase
-
One topic per file — no catch-all documents
-
Link to external sources rather than duplicating content
-
When a process changes, update the doc in the same issue or as a followup actions
-
Before pushing your code, run a local Docusaurus build to preview your markdown changes and verify that all links work. Next, open a pull request and assign a reviewer. Once your PR is approved and merged, our Cloudflare Pages pipeline will automatically handle the deployment.
-
Tag Technical Management for any structural changes (folders, renames, deletions)
Identifying Documentation Needs
- Browse active Slack channels and project boards on an ongoing basis for new subjects that need documentation
- When a board item, an ongoing work, an incident, or discussion introduces a new process, tool, or responsibility with no existing doc, create one or raise it with the relevant Owner
Maintenance & Archival
- Owners review their docs every 2 months at minimum, with the following exceptions:
| Frequency | Documents |
|---|---|
| Monthly | Actively Maintained Repos must reflect current repo activity |
| Monthly | Operational Responsibilities— to account for changes in operational assignments |
| Monthly | Platforms Users Registry— to capture access changes and review unused platforms for potential removal |
-
Docs with no Owner for 6+ months are candidates for archival or removal
-
As a general rule, if someone finding it could act on wrong information, delete it. If it could still inform context, archive it.
-
Archive when the content still has reference or audit value, the domain may return, or the doc was actively used and people may still look for it. To archive:
- Add the notice below at the top, and move the file to the
_archive/directory in the repo root (create it if it doesn't exist) - Then remove the entry from
ownership/documentation-owners.md
> ⚠️ **Archived:** No longer maintained. Archived on {{YYYY-MM-DD}}. Reason: {{reason}}> Original location: [Original file location in the repo] - Add the notice below at the top, and move the file to the
-
Delete when the doc is a duplicate, was never filled for 6 months, contradicts current practice, or was created by mistake.