Skip to content

Contributing documentation

Write Markdown in Git

The docs/ directory is the source of truth. Make changes in a branch, open a pull request, and let the automated build validate the site before merge.

Naming and structure

  • Use lowercase kebab-case for folders and file names: customer-access.md.
  • Use sentence case for page titles: Customer access.
  • Use an action title for procedures: Deploy a customer environment.
  • Use a noun title for reference material: Customer environments.
  • Keep images near the page that uses them, in an assets/ directory.

Required page metadata

Every operational page starts with this front matter:

---
document_status: draft
owner: Engineering
last_verified: YYYY-MM-DD
review_cycle: 6 months
---

Use only these statuses:

Status Meaning
draft Work in progress; do not treat as policy.
approved Reviewed and safe to follow.
deprecated Retained for context; do not use. Link to its replacement.
archived Historical material only.

Review rules

  • The page owner reviews a change to approved documentation.
  • Update last_verified when the page is reviewed, even if its content does not change.
  • Move obsolete material to archive/; do not delete material that may be needed for historical context.
  • Never commit passwords, access tokens, private keys, customer exports, or personal data.