C. Documentation Standards
Wasteology currently operates three documentation surfaces — ADO Wikis, the internal Docusaurus docs site, and per-repo lat.md/ knowledge graphs — with no explicit rule for which to use when. The result is predictable: design intent lives in Slack threads, published how-to pages go stale because no one owns the update cycle, and new team members triangulate between three places to answer a single question. This section establishes opinionated defaults grounded in what already works, so each surface has a clear job and a clear owner.
Decision Framework
The table below is the primary rule. When in doubt, pick the surface whose "owns it when…" description fits the content. Overlap is intentional in one place only: the internal docs site summarizes concepts that lat.md holds in depth — link from docs to lat.md sections, never duplicate prose.
| Content type | Surface | Owns it when… | Never use the other surfaces for this because… |
|---|---|---|---|
| Architecture & design intent | lat.md/ | The content describes why the system is built a certain way and is tied to specific code constructs | A wiki page can't be validated by lat check; docs sites are for readers, not validators |
| API reference (internal) | lat.md/ | The API is owned by this codebase and the spec lives in code | Code and docs drift apart within one sprint without mechanical validation |
| Published how-to for human operators | Internal docs site | The audience is a non-technical teammate or a developer onboarding to a finished feature | lat.md is not indexed or navigable without CLI tooling; wiki pages don't auto-deploy |
| Vendor / customer-facing docs | CRM docs site | The reader is external (CieTrade partner, WDP API consumer, vendor) | Internal and vendor audiences require different trust levels, auth surfaces, and tone |
| Ephemeral meeting notes | ADO Wiki | The content has a date, expires, and is process- not code-tied | Putting meeting notes in docs sites pollutes search; lat.md is code-linked, not event-linked |
| Decision records (ADRs) | ADO Wiki | The decision is org/process-level (vendor selection, team structure, budget) | Code-level decisions belong in lat.md where they can reference the affected code |
| Operational runbooks | ADO Wiki | The runbook describes a manual human process that changes independently of code | Runbooks that are tied to a CLI command should reference the docs site, not duplicate it |
| Onboarding guides | Internal docs site | The audience is a new employee or contractor being oriented to a system | Wiki pages are undiscoverable to new joiners; lat.md requires CLI familiarity |
| Auto-generated visual assets | Internal docs site (static/img/generated/) | NotebookLM or a similar tool produces infographics, slides, or mind maps from docs | lat.md does not render visuals; wikis don't support the <GeneratedVisual> component |
The framework above treats ADO Wiki as strictly non-code content. If the incoming PO prefers ADO Wiki for a broader class of decision records (e.g., product strategy, roadmap), that is fine — but extend the wiki's scope by adding rows to this table, not by using it as a catch-all. Undifferentiated wikis are the starting point of the problem this section solves.
lat.md — Code-Grounded Source of Truth
Current state
Every project in the Wasteology portfolio has (or is converging on) a lat.md/ directory at its root. The knowledge graph is a set of cross-linked markdown files validated by the lat CLI. wg-orchestration has ~12 files covering operations, architecture, platform ecosystem, cloud governance, database schemas, tests, and more. wdp-palantiri, prefect-azure-infrastructure, mars_workorder_system, and tirion each have their own graphs.
Wiki links ([[src/file.ts#function]]) and # @lat: code refs tie sections directly to source code. lat check validates every link on every CI run — if a function is renamed and the lat.md reference is not updated, the check fails. This is the only documentation surface at Wasteology that is mechanically validated against the codebase.
Recommended standard
lat.md is the authoritative source for design intent, data model rationale, test specifications, and internal API contracts. Every developer task ends with two required steps, enforced by the project CLAUDE.md:
Post-task checklist (REQUIRED — do not skip)
After EVERY task, before responding to the user:
- [ ] Update lat.md/ if you added or changed any functionality, architecture, tests, or behavior
- [ ] Run lat check — all wiki links and code refs must pass
No task is considered complete until both steps pass. This is not aspirational — the ADW pipeline enforces it by running lat check as a gate before any PR is submitted.
How it works
The lat CLI provides five commands used daily:
| Command | Purpose |
|---|---|
lat search "query" | Semantic search across all sections — fires automatically on every Claude prompt via UserPromptSubmit hook |
lat locate "Section Name" | Find a section by exact or fuzzy name |
lat refs "file#Section" | Find what references a section (impact analysis) |
lat check | Validate all wiki links and # @lat: code refs — must pass before any commit |
lat expand "user prompt" | Resolve [[refs]] in a prompt to actual file locations |
The lat-md skill (present in every project's .claude/skills/lat-md/) carries the full authoring guide: section structure rules, the 250-character leading-paragraph requirement, wiki link syntax, and require-code-mention frontmatter for test specs.
Freshness mechanism
lat check is the freshness mechanism. A stale lat.md section that references a deleted function fails the check. There is no manual review cadence needed — the check runs on every task completion and on CI.
lat.md currently requires the lat CLI and, for lat search, an LLM API key (LAT_LLM_KEY pointing to an OpenAI- or Gemini-compatible key). If the PO wants non-technical stakeholders to browse design intent without CLI access, the recommended path is to surface selected lat.md sections on the internal docs site via the lat-keeper global agent — not to abandon the code-grounded graph.
Internal Docs Site — Published Human-Facing Documentation
Current state
The Docusaurus monorepo at ~/projects/wasteology-docs/ runs two sites:
- Internal site —
wdp-docs.politegrass-38e79dd2.eastus.azurecontainerapps.io— for Wasteology employees and developers. Current nav: CLI · Dashboard · Account Hierarchy · Infrastructure · AI Tools · QuickBooks · WDP Import · WDP API · Portal Recon · CRM Docs. - CRM site —
crm-docs.politegrass-38e79dd2.eastus.azurecontainerapps.io— vendor-facing. Covers the CieTrade integration surface: account hierarchy, API reference, join patterns, special-account business rules.
Both sites auto-deploy: a push to wasteology-docs/main triggers ADO pipeline ID 8 (wasteology-docs), which builds and deploys both sites via the wg-azure-infra service connection. Manual deployment uses ./scripts/deploy.sh internal|crm.
Recommended standard
The internal docs site owns anything a human needs to read and act on without CLI tooling: onboarding guides, feature how-tos, CLI command references, dashboard walkthroughs, infrastructure overviews, and the AI Tools section for non-technical staff.
The CRM site is the sole home for vendor- and customer-facing documentation. Nothing vendor-facing belongs in the internal site or the ADO Wiki.
Content that belongs here (not in lat.md or wiki):
- Step-by-step guides: "How to run the Portal Recon upload," "How to trigger a WDP import"
- CLI reference pages (the 22
opscommand-group pages) - Dashboard walkthroughs (the 11 wdp-palantiri page guides)
- Onboarding sequences (the 9-page AI Tools section)
- Architecture summaries for non-developer readers (link to
lat.mdfor depth)
How it works — auto-sync
The key mechanism preventing docs rot is docs-triggers.yaml (schema v2), present in each source repo. Each trigger entry declares:
- source_path: "cli/commands/docs.py" # file pattern that triggers an update
target_repo: "wasteology-docs"
docs_site: "internal"
docs_path: "sites/internal/docs"
docs_page: "cli/commands/docs.mdx" # the page to regenerate
Two commands enforce this:
/git-update— runs before every commit; detects whether the staged diff touches anysource_pathpatterns and flags which docs pages need updating. Developers cannot ignore it because it surfaces in the pre-commit flow./docs-update— generates updated MDX content from the changed source code and writes it to thewasteology-docsworking tree. Flags:--commit,--push,--dry-run. The CRM safety check blocks changes to vendor-facing pages unless explicitly confirmed.
The docs-publisher global agent (in wg-agent-infra, symlinked into ~/.claude/agents/) can publish or update docs from any repo without requiring the developer to clone wasteology-docs manually. It reads docs-triggers.yaml at runtime and uses the wg-azure-infra service connection for deployment.
The Azure governance rollout (completed 2026-07-16) is the reference example of this pipeline working end-to-end: code changes in wg-orchestration triggered docs-publisher to update the internal docs site with a "Cloud Governance + azure CLI pages" section, a dashboard page appeared on wdp-palantiri, and a SharePoint onboarding guide was linked from within Claude Code — all without any manual docs-update step by the developer.
Ownership and freshness cadence
| Site | Owner | Freshness gate | Review cadence |
|---|---|---|---|
| Internal site | Lead developer / PO | ops docs freshness — compares source file mtimes vs docs page mtimes | Monthly review of nav structure; per-feature via /git-update |
| CRM site | PO (vendor relationships) | Same ops docs freshness; CRM safety check in /docs-update | Quarterly or on CieTrade API changes |
ops docs freshness is the go-to command to find stale pages. It also checks visual-manifest.yaml for stale generated assets (infographics, slides). Running it before any stakeholder demo is a good habit.
The current internal site nav has 10 sections. As the platform grows, consider whether the PO wants the docs site to also host product specs and roadmaps (currently served as standalone HTML from static/) or keep them separate. The existing pattern (spec.html + roadmap.html linked from sidebar with absolute URLs) works but is outside Docusaurus's content graph — Docusaurus search won't index them.
ADO Wiki — Narrow, Non-Code Scope
Current state
ADO Wiki exists and is used informally across the team for meeting notes, one-off runbooks, and occasional design discussions. There is currently no policy on what goes there, which means it accumulates content that belongs elsewhere — and content that belongs there never gets written because "there's a docs site for this."
Recommended standard
The ADO Wiki has a single, narrow job: org-level and process-level content that is not tied to code and does not need to be publicly navigable.
Belongs in ADO Wiki:
| Content | Why here |
|---|---|
| Meeting notes and sprint retrospectives | Dated, ephemeral, audience is the team |
| Vendor evaluation records (e.g., ConnectorHub vs DevRabbit) | Decision context, not code context |
| Org-level decision records (ADRs for process, not architecture) | Process decisions don't belong in lat.md |
| Budget and billing notes (ADO org billing, subscription assignments) | Sensitive; team-only; not code-tied |
| Manual escalation runbooks for incidents | Human-process, may reference docs site for background |
| Team onboarding checklists (accounts, access, tools) | Org process; complements the docs site's technical onboarding |
Does not belong in ADO Wiki:
| Content | Correct surface |
|---|---|
| Architecture and design intent | lat.md/ |
| CLI command reference | Internal docs site |
| How-to guides for platform features | Internal docs site |
| Vendor-facing documentation | CRM docs site |
| API contracts and data model rationale | lat.md/ |
Ownership and freshness cadence
ADO Wiki content does not have a mechanical freshness gate — that is acceptable because the content is process-level and date-stamped. The recommended practice is a quarterly wiki audit: delete pages older than 12 months that have no forward references, and tag decision records with a status (active, superseded, archived).
The incoming PO may want to use the ADO Wiki for product roadmaps and initiative tracking. The recommendation here is to use ADO Boards (work items + iterations) for that purpose rather than wiki pages — Boards support velocity tracking, linking to PRs, and querying via WIQL, none of which wiki pages provide. If the PO insists on wiki-based roadmaps, establish a naming convention (roadmap/YYYY-QQ-<initiative>) and a quarterly archival rule to prevent the wiki from becoming a graveyard.
Summary: Ownership Matrix
| Surface | Owner | Kept fresh by | Validated by |
|---|---|---|---|
lat.md/ (per repo) | Lead developer on each repo | Post-task checklist; ADW gate | lat check (CLI + CI) |
| Internal docs site | Lead developer + PO | /git-update + /docs-update + docs-publisher agent | ops docs freshness; ADO pipeline ID 8 build |
| CRM docs site | PO (vendor relationships) | /docs-update with CRM safety check | ops docs freshness; same ADO pipeline |
| ADO Wiki | PO | Quarterly audit | Manual; no mechanical gate (acceptable for process content) |
The three surfaces are complementary, not competitive. A well-functioning documentation system at Wasteology looks like this: a developer implements a feature, lat.md captures the design intent tied to the code, /git-update flags which docs page needs updating, /docs-update generates the MDX, the ADO pipeline deploys it, and the PO records the go/no-go decision in the ADO Wiki. No surface duplicates another; no content falls through the gap.