Skip to content

Contributing

This site is built from Markdown files in a Git repo. Anyone on the team can contribute -- no special tooling beyond a text editor and git.

Workflow

  1. Clone the repo and create a branch from main
  2. Add or edit Markdown files in the relevant docs/ section
  3. Preview locally: pip install -r requirements.txt && mkdocs serve
  4. Open a merge request for review
  5. Once merged, the site rebuilds automatically via GitLab Pages

Formatting standards

Document header

Every document should start with a level-1 heading and a metadata block:

# Document Title

**Date:** YYYY-MM-DD
**Author:** Your Name
**JIRA:** [DEVOPSBLN-XXXX](https://tickets.digitalturbine.com/browse/DEVOPSBLN-XXXX)
```text

- **Date** is required on all documents
- **Author** is required -- use your name, not a team alias
- **JIRA** is optional but encouraged for traceability

### Headings

- Use `#` for the document title (one per file)
- Use `##` for major sections
- Use `###` for subsections
- Never skip heading levels (e.g. don't go from `##` to `####`)
- Keep headings short and descriptive

### Code blocks

Always specify the language for syntax highlighting:

````markdown
```bash
kubectl get pods -n monitoring
```yaml

```yaml
syncPolicy:
  automated:
    selfHeal: true

Admonitions

Use MkDocs Material admonitions for callouts:

!!! warning
    This triggers a pod restart. Only use on apps that can tolerate downtime.

!!! info
    Auto-sync stays enabled throughout this procedure.

!!! tip
    Use `--dry-run=server` to preview changes before applying.

Tables

Use Markdown tables for structured comparisons, registries, and decision matrices:

| Column A | Column B | Column C |
|----------|----------|----------|
| value    | value    | value    |
  • Use relative links between documents: [Runbook](../runbooks/2026-02-26_example.md)
  • Use full URLs for external links: [ArgoCD docs](https://argo-cd.readthedocs.io/)
  • Always cross-link related documents (ADR <-> Runbook <-> Test Scenario)

Section-specific conventions

ADRs

  • File naming: NNNN-short-title.md (zero-padded sequential number)
  • Status values: Proposed, Accepted, Deprecated, Superseded by ADR-XXXX
  • Full template in ADR index

Runbooks

  • File naming: YYYY-MM-DD_short-description.md
  • Required sections: Overview, Prerequisites, Procedure, Verification, Rollback, References
  • Full template in Runbook index

Test Scenarios

  • File naming: YYYY-MM-DD_short-description.md
  • Include exact commands run, observed output, and one-line result per test
  • End with a summary table
  • Full template in Test Scenario index

Onboarding

  • File naming: short-topic-name.md (e.g. gcp-access.md)
  • Write for someone on their first day -- assume no prior context about DT systems

Confluence (legacy)

The docs/confluence/ directory contains pages auto-imported from the DEVOPSBLN Confluence space. These pages are read-only in the sense that the next sync will overwrite manual edits.

To refresh Confluence content:

  1. Via CI -- trigger the confluence-refresh manual job in GitLab CI. It downloads pages, runs the post-processor, and generates updated navigation.
  2. Locally -- requires a CONFLUENCE_TOKEN environment variable:
export CONFLUENCE_TOKEN="your-token"
python3 scripts/confluence_download.py
python3 scripts/post_process_confluence.py
python3 scripts/generate_confluence_nav.py --output scripts/confluence_nav.yml

To migrate a Confluence page to native docs: copy the content to the appropriate section (runbooks, ADR, etc.), rewrite it following the section template, and submit an MR. The original stays in docs/confluence/ for reference.

Security: no credentials or secrets in docs

Do not commit literal passwords, API keys, or other secrets in Markdown or config snippets.

  • Use placeholders: '<CHANGE_ME>', '<admin-password>', or (where the tool supports it) ${ADMIN_PASSWORD}.
  • In shell examples use variables only: e.g. curl -u admin:${PASSWORD} and add a one-line note: "Set PASSWORD (or ADMIN_PASSWORD) from your secret store before running."
  • If a snippet shows default values that "must be changed for production," replace the value with a placeholder rather than showing the default.
  • CI runs scripts/check-docs-secrets.sh; the build fails if forbidden patterns (e.g. literal password1, admin:password) are found.

Script/code block rendering: After a Confluence sync, run python3 scripts/post_process_confluence.py --dir docs/confluence so list-item code, bashDNS, and .sh concatenation are fixed. To audit code blocks (no-language fences, four backticks, etc.), run python3 scripts/audit_code_blocks.py --dir docs.

Writing tips

  • Be specific. "Run kubectl get pods -n monitoring" beats "check the pods."
  • Include exact commands. Copy-paste ready is the goal for runbooks.
  • Show output when relevant. Readers should know what success looks like.
  • Date your entries. Prefix knowledge entries with (YYYY-MM-DD).
  • Link aggressively. Every ADR should link to its runbook and test scenario, and vice versa.
  • Keep it current. If a procedure changes, update the doc in the same MR.