Documentation and Knowledge Management Questions

Goal: keep architecture docs accurate, discoverable, and aligned with engineering + sales needs. Lightweight process and checklist a junior SA can follow.

Daily (10–20 min)

• Check doc-change queue/notifications (Confluence/Git/Notion).
• Verify any production incidents/changes that affect runbooks or diagrams.
• Quick update: fix typos, small diagram labels, link missing tickets.
• Notify owner if change > minor via Slack. Reviewer: doc owner (eng lead) for quick ack.

Weekly (30–60 min)

• Review active opportunities (sales) and ensure solution diagram + one-page summary reflect current proposal.
• Scan ADR inbox for new decisions or open PRs; draft new ADRs for architectural choices in proposals.
• Sync with engineering rep (weekly 15-min) to confirm planned infra changes.
• Update runbooks for any recent operational changes; add “tested” tag if exercised.
• Reviewers: engineering peer + sales technical lead. Approval: asynchronous via PR or comment; escalate blocking items in weekly sync.

Monthly (1–2 hours)

• Full doc audit: diagrams, ADRs, runbooks, deployment topology, cost/constraints table.
• Run diagram consistency check (components, versions, network).
• Archive stale docs (>12 months) or mark deprecated.
• Hold monthly review meeting (30 min) with engineering architect and sales lead to approve outstanding ADRs and major diagram changes.
• Formal approval: engineering architect signs off technical accuracy; sales lead signs off customer-facing language. Record approvals in doc footer or PR.

Templates & tooling

• Use templates for ADRs, diagram versioning, and runbooks (preconditions, steps, rollback, owner, last-tested).
• Keep source diagrams in versioned repo; export PNG/PDF for sales collateral.

Escalation & metrics

• If engineering disagrees, route to architecture council or senior SA within 48h.
• Track metrics: docs updated this month, time-to-approval, runbooks tested.

Outcome: reliable, auditable docs that support sales proposals and safe operations with minimal overhead for a junior SA.

Requirements & goals:

• Consistency, auditability, security/compliance, minimal friction for SA agility, clear ownership.

Artifact taxonomy & owners:

• Architecture Diagrams (Logical, Infra, Network): Owner — Lead SA for engagement; Reviewer — Principal Architect + Infra SME.
• Runbooks/Playbooks (ops/run, DR): Owner — SRE/ops SME; Reviewer — SA + Security.
• Proposals/TO-BE Docs: Owner — Proposal SA; Reviewer — Sales Engineering Lead + Compliance.
• POCs/Experiment Reports: Owner — Tech Lead on POC; Reviewer — Principal Architect.

Standard templates (stored in central docs repo):

• Architecture diagram template (layers, components, interfaces, assumptions, constraints, capacity/SLAs) — include Visio/diagrams.net source + exported PNG/SVG.
• Runbook template (purpose, prerequisites, steps, rollback, run frequency, contact list, telemetry/alerts).
• Proposal template (executive summary, scope, non-functional reqs, cost/ops impact, risks, acceptance criteria).
• POC report (objective, success criteria, test results, limitations, next steps).

Review gates & workflow:

• Gate 0 (Draft): Internal author review; optional quick peer read.
• Gate 1 (Technical Review): Required for all artifacts — reviewers listed above; use checklist-based PR.
• Gate 2 (Security & Compliance): Automated scanner + Security reviewer signoff for infra/POC/proposals touching sensitive data.
• Gate 3 (Stakeholder Acceptance): Business/PM/Sales signoff for proposals/major architectures.
• Timebox reviews (48–72 hours to keep velocity).

Version-control & traceability:

• All artifacts in Git-based repository (docs-as-code) with branches, PRs, issue links to customer/engagement ticket.
• Semantic versioning for major changes (vMAJOR.MINOR.PATCH) and changelog per artifact.
• Tag releases per engagement milestone; store binary exports alongside source.

Security & compliance checks:

• Automated linters: secret scanning, IaC policy checks (e.g., tfsec, Checkov), diagram metadata validation.
• Mandatory security checklist embedded in PR template: data classification, encryption, IAM, network segmentation, logging/retention.
• For regulated customers, add checklist for jurisdictional data residency, audit controls, and encryption keys ownership.

Lightweight enforcement & incentives:

• Enforce via CI: PRs cannot merge without passing automated checks and required approvers.
• Exceptions/fast-track: “Rapid” label for <72-hr POCs with time-limited auto-expiry and post-hoc review within 2 weeks.
• SBOM for solution components for procurement/security.
• Metrics & feedback: measure PR lead time, review cycle time, compliance defects; share dashboards monthly.
• Coaching & templates: regular office hours and template updates to lower friction.

Auditability & retention:

• Immutable exports (PDF/PNG) stored in artifact archive per engagement for retention policy (e.g., 7 years).
• Audit log from Git + approval metadata retained; map artifacts to contracts/SOWs.

Rationale:

• Docs-as-code + CI provides low-friction collaboration, audit trail, and automated guardrails. Timeboxed reviews and fast-track paths preserve sales agility while ensuring consistent quality and security.