# Technical Documentation Guide
# Cold Bore Ballistics LLC — Internal Reference
# Classification: Confidential

This guide defines how to write technical documentation: READMEs, runbooks, architecture references, API specs, deployment guides, and rebuild guides. It applies to all documentation across all repos and OneDrive.

Cross-reference: ScopeDOPE_SDLC.md §10 (Documentation Standards) covers documentation as it relates to the ScopeDOPE development process. CBB_SDLC.md §5 covers documentation standards that apply across all CBB projects. This guide covers the writing and formatting decisions that apply everywhere.

---

## 1. The Source-of-Truth Rule

Every piece of information lives in exactly one document. When two documents could logically contain the same fact — a resource ID, a command, a policy — pick one as the source of truth and cross-reference from the other. Duplication creates drift; drift creates incidents.

The Operational Domain Documentation Structure in CLAUDE.md defines which document type owns which content for each infrastructure domain (M365, Atlassian, Azure). Follow it strictly.

---

## 2. Know Your Reader

Before writing any document, answer two questions:

1. **Who is reading this?** (A developer running a script for the first time; a buyer's engineer doing due diligence; an AI agent starting a new session with no prior context.)
2. **What do they need to accomplish?**

Per CLAUDE.md: assume the reader has never used the specific platform, tool, or service being documented. They may be technically capable in general. Do not assume familiarity with the UI, CLI, or terminology. Do not skip steps. Do not say "configure X" without saying how.

---

## 3. Document Types and Structure

### READMEs

Required sections, in order:
1. **One-sentence purpose** — what this repo, tool, or module does
2. **Requirements / Prerequisites** — what must exist before the reader can use this
3. **How to use** — the primary operation(s)
4. Optional: Configuration, Architecture overview, Notes

READMEs cover the thing they live next to. Do not put content that belongs in a runbook or architecture reference into a README.

For tool READMEs (`cbb-utils` subdirectories): a scripts table with one-line purpose per script, followed by expanded documentation of scripts that need it.

### Operating Runbooks

- Open with: what system this covers and who it is for
- Numbered steps for every procedure — order is not optional
- Bullets for reference lists (options, features) — not for steps
- Mark destructive steps with **⚠ Destructive** at the start of the step
- Mark steps requiring human confirmation with `[PROMPT]`
- Every procedure ends with a verification step — what does success look like?
- Multi-platform install instructions where tools must be installed (per CLAUDE.md: Debian, Ubuntu, RHEL/Fedora, Windows, macOS)

### Architecture References

- Record current as-built state only — not what was planned, not what is coming next
- Include all resource names, IDs, and addresses an operator needs to do their job
- Date-stamp the as-built state where the configuration drifts frequently
- Cross-reference the Rebuild Guide for the "how did this get built" narrative; cross-reference the Runbook for operational procedures

### Rebuild / Disaster Recovery Guides

- Open with: what this guide rebuilds and why it exists
- Start with prerequisites: tools, credentials, permissions — what must exist before step 1
- Every step is fully executable — no "configure X" without specifying exactly how, including the exact UI path or CLI command
- Multi-platform tool install instructions for every tool required
- End with a verification section: what must be true for the rebuild to be considered complete

### API Specifications

- Lead with base URL, auth method, and Content-Type expectations
- One endpoint per section
- Request and response schemas documented with field types, constraints, and examples
- Error responses documented alongside success responses — not as an afterthought
- Versioning policy stated explicitly

---

## 4. Markdown Conventions

### Headers

- `#` — document title; one per document
- `##` — top-level sections
- `###` — subsections
- Avoid `####` and deeper — restructure the section instead

### Tables

Use tables for structured reference data: scripts, fields, options, commands. Always include a header row. If a table cell needs more than a sentence, a table is the wrong structure — use a subsection.

### Code blocks

Always use fenced code blocks with a language tag:

```bash
pwsh -NoProfile -File provision_user.ps1
```

Use `bash` for shell commands regardless of the actual shell. Use `kotlin`, `json`, `sql`, `powershell`, `terraform`, `hcl`, `yaml` as appropriate. Never use bare backticks for multi-line code.

### Lists

- Numbered lists for ordered steps — if order matters, it is a numbered list
- Bulleted lists for unordered items — features, options, notes
- Do not mix: a list of steps is numbered even if the steps are short

### Emphasis

- **Bold** for first introduction of a critical term or a warning
- `Code` for all file names, paths, commands, field names, values, and identifiers in prose
- *Italic* sparingly — for titles of documents or genuine emphasis, not decoration

### Currency

Escape the dollar sign in Markdown: `29.99`, `7.75/user/month`. Unescaped `$` is interpreted as a math delimiter by some renderers.

### File and directory names

No spaces — ever. Use underscores. This applies to prose references, code blocks, and file creation.

### Paths in documentation

Never hardcode usernames or home directories (`/home/jschwefel/`, `C:\Users\jason\`). Use repo-relative paths (`cd cbb-infra`) or generic references ("the repo directory"). See CLAUDE.md.

---

## 5. Writing Executable Steps

Each step in a procedure:
1. States the action in imperative form: "Run", "Open", "Navigate to", "Enter"
2. Gives the exact command or UI path
3. Explains the purpose if it is not obvious
4. Notes expected output or confirmation where helpful

**Too vague:**
> Configure the PostgreSQL firewall rule.

**Correct:**
> Run the following to allow the Container App's outbound IP to connect to the database. Replace `<OUTBOUND_IP>` with the IP shown in the Container App overview blade in the Azure Portal:
>
> ```bash
> az postgres server firewall-rule create \
>   --resource-group rg-cbb-prod \
>   --server-name <server-name> \
>   --name allow-containerapp \
>   --start-ip-address <OUTBOUND_IP> \
>   --end-ip-address <OUTBOUND_IP>
> ```
>
> Verify with `az postgres server firewall-rule list --resource-group rg-cbb-prod --server-name <server-name>`.

---

## 6. Keeping Documentation Current

- When code changes, update the relevant doc in the same commit
- When a configuration change is applied to live infrastructure, update the Architecture Reference before closing the session
- When a procedure changes, update the Runbook immediately — a stale runbook is more dangerous than no runbook, because it is followed with false confidence
- If a document is incomplete, say so at the top: "**Draft — sections 4–6 not yet written.**"

---

## 7. Document Footer — Mandatory for All Documents

Every CBB document in OneDrive must end with two blocks, in this order, as the final sections of the file.

### Document Control

Captures the static identity and metadata of the document. Fields:

| Field | Notes |
|---|---|
| **Document owner** | Always `jschwefel@coldboreballisticsllc.com` until additional staff are onboarded |
| **Classification** | Derived from the OneDrive tier the file lives in (see §8) |
| **Location** | Full OneDrive-relative path starting with `OneDrive/` |
| **Cross-references** | Other CBB documents this document explicitly references, by filename |
| **Created** | Date the document was first written |
| **Last updated** | Date of the most recent edit |
| **Next full review due** | Created date + 1 year; reset after each full review |

Example:

```markdown
## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (`03_-_Confidential/`) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Example_Doc.md` |
| **Cross-references** | `M365_Architecture_Reference.md`; `CBB_Information_Security_Policy.md` |
| **Created** | 2026-06-07 |
| **Last updated** | 2026-06-07 |
| **Next full review due** | 2027-06-07 |
```

### Revision Control Block

A log table. Each row records one revision. Add a new row every time the document is materially updated — do not edit existing rows.

- **Rev** — starts at `0.9`; advances to `1.0` at ScopeDOPE 1.0.0 release; increments by `0.1` for minor updates, `1.0` for major rewrites thereafter
- **Date** — date of the change
- **Changed By** — the person or tool that made the change
- **Reviewed By** — `—` if not formally reviewed
- **Approved By** — `—` if not formally approved
- **Summary** — one-line description of what changed

Example:

```markdown
## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-07 | jschwefel | — | — | Initial release |
| 0.9.1 | 2026-06-14 | jschwefel | — | — | Added §4 examples |
```

---

## 8. Classification and Trade Secrets

- `OneDrive/04_-_Highly_Confidential/` — engine internals, DOPE-Blend methodology, the SPEC. Never quote in READMEs, commit messages, or Jira tickets.
- `OneDrive/03_-_Confidential/` — operational and strategy docs. Internal only.
- `OneDrive/02_-_General/` and `01_-_Public/` — may be shared externally or with contractors under NDA.
- Public repos (`dope-format`) — only content appropriate for public consumption. The dope-format SPEC.md is intentionally public; nothing in `04_-_HC` is.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Style_Guides/TECHNICAL_DOCUMENTATION_GUIDE.md` |
| **Cross-references** | `CODING_STYLE_GUIDE.md`; `INTERNAL_WRITING_GUIDE.md`; `BRAND_LEGAL_LANGUAGE_GUIDE.md` |
| **Created** | 2026-06-04 |
| **Last updated** | 2026-06-09 |
| **Next full review due** | 2027-06-04 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-04 | jschwefel | — | — | Initial release |
| 0.9.1 | 2026-06-07 | jschwefel | — | — | Added §7 mandatory document footer SOP; renumbered Classification to §8 |
| DRAFT | 2026-06-09 | Claude Code | — | — | Removed non-standard `# Last Updated` header line (it contradicted Document Control and violated this guide's own §7 rule that the date lives only in the footer blocks). No content changes. |
