Technical Writing and Documentation Questions

How-to (procedural) vs Why (architectural rationale):

How-to (procedural)

• Purpose: Step-by-step instructions to perform tasks—deploy, configure, operate. Focuses on execution, reproducibility, and runbooks.
• Example artifact: Deployment runbook or CI/CD pipeline playbook that lists commands, parameters, scripts, and rollback steps.
• When to include: Deliver with implementation handoff, runbooks in the final implementation package, or during onboarding/handover to operations. Critical when teams must execute repeatable tasks reliably and quickly.

Why (architectural rationale)

• Purpose: Explains decisions, trade-offs, constraints and alternatives so future readers understand design intent and can evolve the system safely.
• Example artifact: Architecture decision record (ADR) documenting chosen database, why it was selected (scalability, consistency), rejected options, and impact.
• When to include: Include early (proposal/solution design) and in the final architecture docs. Essential during sales/approval, peer reviews, and when maintenance or re-architecture decisions are anticipated.

Best practice: Provide both. Pair ADRs (why) with concrete runbooks/configs (how) so implementers know what to do and why decisions exist.

ARB Submission Template — Distributed Caching Layer

1. Executive Summary

• Purpose: (one-paragraph summary of change and business drivers)
• Scope: (systems/components impacted)
• Owner: (team, primary contact, date)

2. Functional Requirements

• Data types cached
• Read/write semantics (TTL, invalidation)
• Consistency model (strong/causal/eventual)
• API surface (get/put/delete/bulk ops)
• Integration points (services, CDNs, DBs)

3. Non-Functional Requirements

• Latency targets (p99, p50)
• Throughput (RPS)
• Availability/SLA
• Durability (persistence/replication)
• Capacity (memory, node count)
• Cost constraints

4. Capacity Planning

• Expected peak and baseline RPS
• Expected hit ratio and effective DB load reduction
• Sizing calculations (nodes, RAM, network)
• Growth projections and headroom

5. Security Considerations

• Network segmentation, ACLs
• Encryption (in-transit, at-rest)
• AuthN/AuthZ (mTLS, IAM)
• Secrets management
• Data sensitivity and PII handling
• Audit/logging requirements

6. Failure Modes & Mitigations

• Node failure, network partition, cache stampede, stale reads, data loss
• Detection and automated mitigation strategies

7. Testing Plan

• Unit, integration, chaos/failure injection
• Load/stress tests with realistic patterns
• Consistency and TTL/eviction tests
• Security/pen tests

8. Rollout Strategy

• Phased rollout (canary, regional, percentage)
• Feature flags, traffic steering
• Runbooks and run-stage criteria

9. Rollback Plan

• Criteria for rollback
• Steps to revert config/code and restore traffic
• Data reconciliation steps

10. Monitoring & Alerting

• Key metrics, dashboards
• Alert thresholds and runbooks
• On-call responsibilities

11. Dependencies & Alternatives

• Third-party services, infra changes, DB mods
• Alternatives considered and trade-offs

12. Risk & Compliance

• GDPR, HIPAA impacts, vendor lock-in risks

Filled Example — Distributed Caching Layer for Online Retail Checkout

1. Executive Summary
   Purpose: Introduce a distributed caching layer (Redis Cluster) fronting checkout/session service to reduce DB load and improve p99 latency from 250ms→50ms. Scope: Checkout service, Session microservice, cart DB reads. Owner: Solutions Architecture (alice@example.com), 2025-11-10.

2. Functional Requirements

• Cache user sessions, product price lookups, cart totals (JSON blobs)
• Read-mostly; writes on cart update and checkout
• TTL: sessions 24h sliding; price lookup 15m with invalidation on price change via event
• APIs: GET/SET/DEL, bulk MGET/MSET for cart items
• Integration: Checkout API, Pricing Service events, Postgres primary for writes

3. Non-Functional Requirements

• Latency: p50 < 5ms, p99 < 20ms for cache hits
• Availability: 99.99% regional; tolerate single-node failure
• Durability: replication factor 3, async AOF disabled (in-memory) — DB is source of truth
• Cost: target infra < $15k/mo

4. Capacity Planning

• Baseline traffic: 10k RPS reads, 500 RPS writes; Peak: 40k RPS (sale events)
• Desired hit ratio: 92% → DB effective read load = 40k * (1-0.92) = 3.2k RPS
• Each cached object avg 2 KB. Memory = peak RPS * objects_per_req * avg_ttl_estimate:
  Estimation: 5M unique session/cart objects * 2KB = 10 GB. Add 50% overhead → 16 GB usable.
• Cluster: 6 nodes (r5.large equivalent), 32GB RAM each, shard + replica (3 shards x 2 replicas) to meet capacity and replication
• Network: 1 Gbps per node; expected network egress within limits
• Headroom: plan for 2x traffic growth in 12 months

5. Security Considerations

• Private VPC, no public endpoints; restrict CIDR to app subnets
• mTLS between services and Redis via stunnel with mutual certs managed by Vault
• Enable TLS in-transit; at-rest encryption via host-disk encryption (EBS)
• RBAC via service accounts; audit logging forwarded to SIEM
• Mask PII: sessions hold only user_id and pointer to PII stored in DB; no raw credit card data cached

6. Failure Modes & Mitigations

• Node failure: automatic failover via cluster; traffic routed to replicas
• Network partition: clients fallback to DB reads with throttling and circuit breaker
• Cache stampede: implement request coalescing (singleflight) + early recompute with jittered TTL
• Eviction/stale data: apply versioning + event-driven invalidation on price change
• Complete cluster outage: degrade gracefully—read-through to DB and show degraded UX banner

7. Testing Plan

• Unit tests for cache client library; integration tests with Redis in CI
• Load test: simulate 40k RPS with real key distribution (zipfian) and 92% cache hit; validate latency and DB load
• Chaos: terminate nodes, simulate network partition, and validate failover <5s
• Eviction and TTL tests: verify correctness post-eviction
• Security tests: vulnerability scan, cert rotation test, penetration test on staging

8. Rollout Strategy

• Stage 1: Deploy cluster in staging, run full test suite
• Stage 2: Canary 1% traffic in us-east-1 for 24h, monitor KPIs
• Stage 3: Gradually increase to 10%, 50%, 100% over 3 days contingent on KPIs
• Use feature flag and traffic-shaping; enable read-through mode initially

9. Rollback Plan

• Criteria: sustained p99 latency > 2x baseline, DB error rate increase > 30%, data inconsistency > threshold
• Steps: shift traffic back to DB-only via feature flag; disable writes to cache; decommission cache cluster if needed
• Post-rollback: requeue invalidation events and reconcile cache with DB; run consistency check job

10. Monitoring & Alerting

• Dashboards: cache hit ratio, read/write RPS, p50/p95/p99 latencies, evictions/sec, memory utilization per node, replication lag, cluster health
• Alerts:
  • Critical: node down + not recovered in 60s → page SRE
  • Critical: hit ratio drops >10% absolute for >5m → page on-call
  • Warning: memory usage > 85% on any node → email + Slack
  • Warning: p99 latency > 50ms for 5m → notify
• Logs: access logs, slow commands (>10ms), auth failures forwarded to SIEM
• Runbooks: include recovery steps for failover, eviction handling, cert rotation

11. Dependencies & Alternatives

• Dependencies: event bus (Kafka) for invalidation events, Vault for certs, Postgres schema for eventual reconciliation
• Alternatives considered: managed ElastiCache Redis vs self-hosted Redis Enterprise — selected managed Redis Cluster for operational simplicity; trade-off: vendor lock-in vs operational savings

12. Risk & Compliance

• Risk: cache misconfiguration exposing PII — mitigated by design and audits
• Compliance: no sensitive payment data cached; architecture reviewed by compliance team

Approvals Requested: Architecture review, security review, budget sign-off for managed Redis cluster.

Clarifying requirements:

• Ingest Visio (.vsdx), draw.io (.drawio/.xml), PlantUML (.puml/.txt), Lucidchart (exported .vdx/.svg or via API), plus binary blobs stored in drives.
• Output: canonical, versionable artifacts (preferred: diagrams-as-code like PlantUML/Graphviz or normalized SVG + structured metadata) committed to Git with diffs and CI validation.
• Non-functional: repeatable, auditable, best-effort fidelity, handle manual edits, scalable.

High-level pipeline:

1. Ingestion layer
   • Connectors: watch folders, cloud storage, Lucidchart/Visio APIs.
   • Normalize inputs to a staging area with provenance metadata (source, timestamp, user, original file).
2. Format detection & extractor
   • Use format-specific parsers:
     • Visio: use Apache POI/Visio SDK or MS Graph export to SVG/VDX; extract shapes/text/custom properties.
     • draw.io: XML -> canonical intermediate (diagram JSON).
     • Lucidchart: export to SVG or JSON via API.
     • PlantUML: already diagrams-as-code — canonicalize formatting.
   • Produce a unified intermediate model (nodes, edges, shapes, styles, layers, annotations) expressed as JSON Schema.
3. Canonicalization / conversion
   • Two output paths:
     a) Diagrams-as-code generator: map intermediate model to PlantUML (or Mermaid) templates where semantics map cleanly (classes, flows, components).
     b) Annotated SVG generator: render SVG with embedded metadata as <metadata> or data-* attributes and produce a small companion YAML/JSON with provenance and editable coordinates.
4. Validation & CI
   • Linting (style rules), round-trip checks (convert out->in for formats that support), visual diff generation (pixel diff or structural SVG diff).
   • Automated tests ensure parsers don't lose critical semantic properties.
5. Versioning & storage
   • Store canonical artifacts (PlantUML/mermaid + metadata OR annotated SVG + JSON) in Git repo. Store original binary in an artifact store linked by pointer.
   • Use commit hooks/PR templates to require that manual edits include reason/provenance.
6. UI & manual edit workflow
   • Provide a lightweight web UI to preview, edit metadata, and edit diagrams-as-code. For WYSIWYG edits, allow export back to draw.io/SVG and store both the edited canonical form and the exported format.
   • Conflict resolution: require edits to canonical source (diagrams-as-code) as primary; generated formats are derived artifacts. For users who insist on GUI editors, provide two-way sync where feasible and flag mismatches for human review.

Trade-offs and limitations:

• Fidelity loss: Some proprietary Visio/Lucidchart features (smart shapes, certain behaviors, macros, embedded data) cannot be perfectly mapped to diagrams-as-code — expect best-effort mapping and store originals. High-fidelity rendering should use SVG export; semantics-to-code may be lossy.
• Ambiguity in semantics: Visual positioning vs. semantic relationships — diagrams-as-code focuses on semantics, not absolute layout. If layout is essential, store coordinates in metadata or prefer annotated SVG.
• Round-trip edits: Two-way conversion is hard; perfect round-trip for all features is infeasible. Minimize by encouraging edits in canonical format (code-first) and providing tooling to ease that transition.
• Tooling maintenance: Parsers and mappers require continuous maintenance as vendor formats change. Mitigate by modular connectors and tests.

Handling manual edits:

• Make diagrams-as-code the source of truth for versioning and code review.
• For users needing WYSIWYG, provide tooling that edits the canonical model (not only generated SVG) and emits diffs to PRs.
• If a user edits exported SVG/draw.io directly, detect divergence via CI; create an automated PR that attempts to re-canonicalize and flags conflicts requiring human reconciliation.
• Enforce provenance: every commit includes metadata (original author, tool, edit type). Maintain an audit trail and retain originals for irreversible features.

Operational considerations:

• Start with incremental roll-out: support PlantUML, draw.io, and SVG first; add Visio/Lucidchart connectors next.
• Provide migration guidelines and training to nudge teams toward diagrams-as-code.
• Monitor conversion accuracy via sample audits and user feedback; iterate converters.

This design balances traceability and versionability (Git + code-first) with pragmatic fidelity (annotated SVG + originals) and enforces workflows that minimize lossy round-trips while keeping authors productive.

Requirements clarification: regulated enterprise needs strong compliance (audit trails, data residency), tight source-control integration, excellent search, low operational burden, and minimal vendor lock‑in risk.

Decision matrix (weights sum = 100):

Criteria (weight) | Build score (1–5) | Buy score (1–5)

• Cost (20): Build 2 — Buy 4
• Maintenance & Ops (15): Build 2 — Buy 5
• Customization & UX (15): Build 5 — Buy 4
• Security & Compliance (20): Build 4 — Buy 4 (if vendor certified)
• Integration with Source Control (10): Build 4 — Buy 4
• Search Quality (10): Build 3 — Buy 5
• Vendor Lock-in Risk (10): Build 5 — Buy 2

Weighted total:

• Build = 220 + 215 + 515 + 420 + 410 + 310 + 5*10 = 40+30+75+80+40+30+50 = 345
• Buy = 420 + 515 + 415 + 420 + 410 + 510 + 2*10 = 80+75+60+80+40+50+20 = 405

Interpretation & recommendation:

• Buy scores higher (405 vs 345) driven by lower TCO, minimal ops burden, and superior search. For a regulated enterprise, choose a SaaS documentation platform only if it meets strict controls: SOC2/ISO27001, contractual data residency, audit logs/exportable logs, SSO + SCIM, ability to integrate with on‑prem source control or enable repository mirroring, and exportable full data export to mitigate lock‑in.
• If no vendor meets those compliance/exit criteria, prefer build with a phased plan: implement minimum viable docs platform using open-source stack + hardened deployment, and plan 12–18 month revisit for re-evaluation.

Risk mitigations if buying:

• Contract SLAs, right-to-extract data, encryption key ownership (BYOK), periodic compliance attestation, and vulnerability scanning results.

This decision balances speed, total cost, and regulatory constraints while preserving an exit path.

Overall critique:
The excerpt and diagram are too terse and ambiguous for a solutions-architecture audience. They omit protocols, responsibilities, performance expectations, failure modes, and operational details. The ASCII diagram lacks directionality of data flows, latency/throughput expectations, authentication, and which component owns the cache or sharding logic.

Concrete edits (at least five):

1. Expand sentences into explicit statements: e.g., "Service A calls Service B using HTTPS REST (JSON) with OAuth2 token-based authentication."
2. Specify caching: "Add a shared Redis cache in front of Service B for read-heavy endpoints; include TTL of 60s and cache key strategy."
3. Clarify DB sharding: "Primary-key based sharding by customer_id across N shards (Postgres v13), with shard map stored in config service; describe re-sharding plan."
4. Add non-functional requirements: "Target p99 latency <200ms, throughput 5k req/s, and availability 99.95%."
5. Define error handling and retries: "Service A retries idempotently up to 2 times with exponential backoff; circuit breaker with 5 failures threshold."
6. Improve diagram: show cache, load balancers, auth, arrows for request/response, and annotate components with protocols and SLAs.

Three missing artifacts to add:

1. Sequence diagram for key workflows (successful call, cache miss, DB failover).
2. Deployment/infra diagram showing load balancers, autoscaling, monitoring, and where the cache and shards live.
3. Operational runbook/SLAs and failure-mode matrix (alerts, rollback steps, data-consistency guarantees).