Review: Published Implementation Guides
Reviewed: July 22, 2026
Note: Scores marked with * were from the July 2026 review when implementation guides were scored against the solution rubric. Re-scoring against README-best-practices-implementation.md is planned.
Scorecard
| Rank | Implementation Guide | Score | Verdict |
|---|---|---|---|
| 1 | AAP HA/DR on OpenShift | 9.8/10* | Reference-grade implementation guide with validated test scenarios, observed SLAs, and production-hardened failover runbooks |
| 2 | Zero Trust Architecture with Ansible | 9.6/10* | Five integrated use cases demonstrating defense-in-depth: OPA policy gates, SPIFFE workload identity, JIT credentials, and break-glass recovery with phased implementation roadmap |
| 3 | AI-Assisted Ansible Developer Experience | 9.5/10* | Comprehensive DevTools guide with four installation methods, MCP integration, and enterprise maturity model from individual to governed |
| 4 | OpenShift EDA + Kafka Event Pipeline | 9.2/10* | Deep integration guide: full Kafka/Serverless/EDA pipeline with custom credential types, alternative architectures, and strong validation |
| 5 | High-Availability AAP with EDB PostgreSQL DR | 8.7/10* | Reference-grade VM-based DR architecture with diagrams, runbooks, and failback procedures |
| 6 | AI Infrastructure automation with Ansible | 7.3/10* | Clear two-collection story (infra.ai + redhat.ai); needs framework alignment and deeper validation |
| 7 | Intelligent Assistant with Red Hat AI Inference Server | 6.9/10* | Strong hands-on RHAIIS + Lightspeed hookup; weakest framework alignment of published guides |
| 8 | PostgreSQL Autovacuum Tuning | Pending review | Published; not yet scored against the Implementation Guide rubric |
How This Was Scored
Implementation guides will be evaluated against the quality scoring model from Best Practices for Writing Implementation Guides:
| Category | Weight |
|---|---|
| Outcome Clarity (platform/deployment goal) | 15% |
| Architecture Clarity | 25% |
| Technical Executability | 25% |
| Validation/Testability | 20% |
| Production and Day-2 Readiness | 15% |
Score each category 1-5. Multiply by weight. Final score out of 10. Any category below 3 means revise before publishing.
Scores marked with * in the scorecard above used the solution guide rubric during the July 2026 review and will be updated when re-scored.
Guide Reviews
1. High Availability and Disaster Recovery for AAP on OpenShift
File: README-AAP-HA-DR-OpenShift.md Score: 9.8 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 5 |
| Architecture Clarity (20%) | 5 |
| Technical Executability (25%) | 5 |
| Validation/Testability (15%) | 5 |
| Production Readiness (10%) | 5 |
| Business Framing (10%) | 4 |
| Stats: ~8,500 words | 12+ YAML blocks | 1 clickable architecture image + 1 Mermaid diagram | 6 major sections with appendix | Validated test scenarios table |
Strengths:
- Extraordinary depth: full operator Subscriptions, CNPG Cluster CRs with production-tuned PostgreSQL parameters, complete AAP CR with node scheduling
- Validated test scenarios with observed SLAs – pod recovery (6-59s), DB failover (33-44s), node failure (~7min), full region DR (11-79s)
- Two failover procedures (controlled switchover vs emergency) with exact
oc patchcommands and step-by-step token flow - Day 2 operations section: backup/restore, DB maintenance, certificate rotation, monitoring stack with key metrics and alert thresholds
- Known Issues section documents real bugs with workarounds (metrics service, stale OAuth2 secret, ODF RGW pg_num)
- Planning section on physical placement, distance, and external dependencies is unusually thoughtful for a technical guide
- Appendix A provides full ODF RGW multisite bootstrap with
radosgw-admincommands and upstream bug references
Weaknesses:
- No demos, videos, or interactive walkthroughs
- Business framing is present (persona table, maturity path) but lacks quantified cost/MTTR savings
- The guide is extremely long – may benefit from being split into “Architecture + Planning” and “Implementation” documents
- Missing KB blockquote under the title
Suggestions:
- Add a brief executive summary or “Quick Start” at the top for architects who need the architecture without the full implementation
- Consider a companion reference card (one-pager) with the validated SLA table and failover cheat sheet
- Add a cost/resource estimate section (node count, storage, operator overhead)
2. Zero Trust Architecture with Ansible Automation Platform
File: README-ZTA.md Score: 9.6 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 5 |
| Architecture Clarity (20%) | 5 |
| Technical Executability (25%) | 5 |
| Validation/Testability (15%) | 5 |
| Production Readiness (10%) | 4.5 |
| Business Framing (10%) | 4 |
| Stats: ~7,800 words | 12+ YAML/bash code blocks | 5 integrated use cases | Per-use-case validation suites | 9-row troubleshooting table | Phased implementation roadmap with success criteria | Measuring Success metrics table |
Strengths:
- Five integrated use cases that build on each other: verification -> JIT credentials -> policy enforcement -> workload identity -> defense-in-depth. The progression tells a coherent story
- OPA policy enforcement at two rings (platform gateway + in-playbook) is the most sophisticated authorization model in any guide
- SPIFFE/SPIRE workload identity verification is unique across all guides – cryptographic proof that the automation platform is legitimate
- Defense-in-depth use case with deliberate lockout scenario and tested break-glass recovery is exceptional – teaches incident response, not just happy-path automation
- Comprehensive validation test suite with deny/allow scenarios for every use case, including “wrong user”, “wrong VLAN”, “wrong SPIFFE ID” negative tests
- Phased implementation roadmap (Crawl/Walk/Run) with specific week estimates and success criteria for each phase
- Measuring Success table with baseline vs. target metrics and measurement methods
- Source code repository linked directly (nmartins0611/zta-workshop-aap)
- Credential lifecycle timeline table showing exactly what happens from T+0 to T+301s
Weaknesses:
- No Mermaid architecture diagram (workflow patterns described in text only)
- No demos, videos, or interactive walkthroughs (workshop link is good but not an embedded demo)
- Business Framing relies on bold percentages in Summary rather than a dedicated ROI Recap section
- Empty HTML anchor tags (
<h2 id="..."></h2>) clutter the source but don’t affect rendering
Suggestions:
- Add a Mermaid diagram showing the defense-in-depth rings and OPA policy enforcement flow
- Consider recording a demo of the break-glass recovery scenario – it’s the most dramatic and teachable moment
- Add an embedded Arcade walkthrough for the workshop if available
3. AI-Assisted Ansible Developer Experience
File: README-Ansible-DevTools.md Score: 9.5 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 4.5 |
| Architecture Clarity (20%) | 5 |
| Technical Executability (25%) | 5 |
| Validation/Testability (15%) | 4 |
| Production Readiness (10%) | 5 |
| Business Framing (10%) | 5 |
| Stats: ~4,800 words | 3 Mermaid diagrams + multiple code blocks (bash, JSON, YAML) | 4 installation methods with step-by-step | MCP server configuration section | Comprehensive comparison table |
Strengths:
- Four installation methods (uv/pip, RPM, Dev Container, Dev Spaces) with clear “best for” guidance and honest tradeoffs
- Three Mermaid diagrams: delivery method progression, tool lifecycle (Create/Test/Deploy), and MCP architecture
- MCP section covers both Ansible Devtools MCP server and AAP MCP server with configuration examples for Claude Code, VS Code, and
.mcp.json - End-to-end development workflow showing scaffold -> lint -> inventory check -> run on AAP -> troubleshoot loop
- Comparison table across 11 dimensions is immediately actionable for decision-makers
- Maturity path goes to four levels (Crawl through “Fly”) – first guide to do so, appropriate for the topic
- Both upstream (community) and downstream (Red Hat supported) paths documented side by side
Weaknesses:
- Borderline solution vs. tutorial – the framing around “enterprise developer experience” saves it, but the guide could be read as “how to install ADT”
- Validation is relatively simple (
adt --version+ smoke test) compared to the complexity of what’s being set up - No screenshots of the Dev Container or Dev Spaces experience in action
- Missing KB blockquote under the title
Suggestions:
- Add a screenshot or two showing the dev container experience (VS Code with Ansible extension running inside the container)
- Strengthen the validation section with a more meaningful test (e.g., scaffold a role, lint it, run molecule)
- Add a “Common questions from leadership” FAQ addressing cost justification for Dev Spaces infrastructure
4. OpenShift EDA + Kafka Event Pipeline
File: README-OpenShift-EDA-Kafka.md Score: 9.2 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 4 |
| Architecture Clarity (20%) | 5 |
| Technical Executability (25%) | 5 |
| Validation/Testability (15%) | 5 |
| Production Readiness (10%) | 4 |
| Business Framing (10%) | 4 |
| Stats: ~5,200 words | 15+ YAML/shell blocks | 1 Mermaid diagram | 7 numbered walkthrough steps | Per-stage validation table + 7-row troubleshooting table |
Strengths:
- Complete pipeline from Kubernetes API to EDA: APIServerSource -> KafkaSink -> Kafka -> EDA -> AAP job template, all with deployable CRs
- Custom credential type for Kafka with field definitions and injector configuration – uncommonly detailed
- Alternative architecture comparison (direct KafkaSink vs KafkaChannel + Subscription) with strengths/limitations table
- CloudEvents table documenting the three event types captured with their triggers and payloads
- Full EDA rulebook with three condition rules and a catch-all debug rule
- Honest scoping: “This guide builds the foundational event pipeline” with Maturity Path showing the path to automated governance
Weaknesses:
- The immediate outcome is “log namespace events” – deliberately basic, but a reader might feel underwhelmed after deploying Kafka + Serverless + EDA
- No demos, videos, or interactive walkthroughs
- No quantified business value (time savings, audit compliance improvement)
- Missing KB blockquote under the title
Suggestions:
- Add a “What you can build on this” section with 2-3 concrete examples (e.g., auto-apply network policies to new namespaces, alert on label violations)
- Consider adding a simple governance action in a “bonus step” to show immediate value beyond logging
- Add cost/resource notes for the Kafka + Serverless stack (storage, operator overhead)
5. High-Availability AAP with EDB PostgreSQL DR
File: README-EDB.md Score: 8.7 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 4.5 |
| Architecture Clarity (20%) | 5 |
| Technical Executability (25%) | 4 |
| Validation/Testability (15%) | 4 |
| Production Readiness (10%) | 4 |
| Business Framing (10%) | 4.5 |
| Stats: ~7,130 words | 1 YAML block | 3 Mermaid diagrams (architecture, data flow, failover sequence) | 6 phases, 23 titled substeps |
Strengths:
- Reference-grade architecture: Mermaid diagrams (dual-DC topology, steady-state data flow, failover sequence) plus sizing and component tables
- Operational honesty about failover impact on sessions, in-flight jobs, EDA activations, and DNS TTL
- End-to-end scope from infrastructure provisioning through production cutover, plus an Operational Runbook section
- Strong validation surface: per-stage checklist, health-check scripts, failback procedure, and troubleshooting table
- Clear “Who Benefits” and Crawl/Walk/Run tables connecting engineering work to stakeholder language
Weaknesses:
- Unified INI inventory example for DC2 may have grouping issues that could cause install failures if copied literally
- Failover testing alternates between
pg_ctl promoteand EFM-orchestrated behavior without a clear single authority - Unlike other AAP guides, there is no featured Automation Hub collection table (fine for the topic, but a convention gap)
- Missing KB blockquote under the title
Suggestions:
- Validate and fix the unified inventory INI grouping so DC2 host/variable assignments are unambiguous
- Add a short “Support and boundaries” note clarifying Red Hat vs EDB support scope
- For 3-5 key commands (
podman ps,efm cluster-status,pg_is_in_recovery), show verbatim expected output
6. AI Infrastructure automation with Ansible
File: README-IA.md Score: 7.3 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 4 |
| Architecture Clarity (20%) | 4 |
| Technical Executability (25%) | 4 |
| Validation/Testability (15%) | 3 |
| Production Readiness (10%) | 3 |
| Business Framing (10%) | 3 |
| Stats: ~1,927 words | 3 YAML blocks | 1 workflow screenshot | ~8-10 major phases |
Strengths:
- Clear two-collection story (
infra.aifor provisioning,redhat.aifor model serving) with Automation Hub links - Multiple integration paths: CLI inventory vs AAP EC2 sync, curl vs Ansible module for validation
- Honest scope note that AWS is an example while
infra.aisupports other targets
Weaknesses:
- Missing canonical Overview, Prerequisites, and Maturity Path sections per the framework
- Validation has no verbatim expected output and no troubleshooting table
- No persona table, no quantified business pain
Suggestions:
- Add an Overview section with a problem statement and consolidated Prerequisites table
- Expand Validation with sample success output and a 3-5 row troubleshooting table
- Add persona mapping and business framing
7. Intelligent Assistant with Red Hat AI Inference Server
File: README-Intelligent-Assistant-RHAIIS.md Score: 6.9 / 10*
| Category | Score |
|---|---|
| Outcome Clarity (20%) | 4 |
| Architecture Clarity (20%) | 3 |
| Technical Executability (25%) | 3 |
| Validation/Testability (15%) | 4 |
| Production Readiness (10%) | 3 |
| Business Framing (10%) | 4 |
| Stats: ~1,625 words | 0 YAML blocks (2 YAML snippets in ~~~ fences) |
Arcade demo + 1 GPU screenshot | ~12-14 major operations |
Strengths:
- Tight integration target: connects RHAIIS container flags required for Lightspeed
- Actionable OpenShift wiring: Kubernetes Secret keys and AAP CR spec.lightspeed fields
- Concrete validation with curl test and expected answer text
- Rich Arcade demo embed for visual learners
Weaknesses:
- Missing framework sections: no Overview, Solution (components/personas), Workflow/Architecture, or Maturity Path
- No formal architecture diagram
- YAML snippets use
~~~fences instead of ` ```yaml `
Suggestions:
- Add an Overview with problem statement and a Workflow section with a simple diagram
- Fix
podman runformatting; convert~~~to ` ```yaml ` - Add a Validation heading with a troubleshooting table
8. PostgreSQL Autovacuum Tuning
File: README-AAP-PostgreSQL-Autovacuum-Tuning.md Score: Pending review
Published since the July 2026 review. Not yet scored against the Implementation Guide rubric.
Cross-Cutting Observations
What changed since the May 2026 review:
- Four implementation guides scored 9.2-9.8*, raising the quality bar significantly
- AAP HA/DR on OpenShift is the deepest single guide in the collection and introduces the “validated test scenarios with observed SLAs” pattern – all other implementation guides should aspire to this level of production evidence
- Mermaid adoption is now standard – all new implementation guides use Mermaid diagrams (the convention rule change is paying off)
- MCP coverage is growing – the DevTools guide documents MCP server integration with configuration examples for multiple IDEs
Patterns that work well across implementation guides:
- Per-stage operational impact tables (HA/DR, EDB, OpenShift-EDA)
- Mermaid diagrams for workflow and architecture visualization (HA/DR, EDB, OpenShift-EDA, DevTools)
- Alternative architecture comparison tables (OpenShift-EDA: KafkaSink vs Channel)
- Validated test scenarios with timing data (HA/DR)
- Phased implementation roadmaps with success criteria (ZTA)
- Day 2 operations and known-issues sections (HA/DR)
Recurring gaps across implementation guides:
- Source repo links – many guides show code excerpts but don’t link to a full runnable repo (ZTA is a positive exception)
- Cost/resource estimates – only DevTools addresses infrastructure cost questions consistently; HA/DR and OpenShift-EDA would benefit from node/storage estimates
- Missing KB blockquotes – HA/DR, DevTools, OpenShift-EDA, and EDB lack the legacy KB link under the title
- Framework alignment – AI Infrastructure and RHAIIS need canonical Overview, Prerequisites, and Maturity Path sections before re-scoring
Ranking rationale:
- HA/DR on OpenShift (9.8*) leads on raw depth, validated SLAs, and production-hardened failover runbooks
- ZTA (9.6*) is the most sophisticated authorization and identity model with five integrated use cases and break-glass recovery
- DevTools (9.5*) is the broadest developer-focused guide with four installation paths and MCP integration
- OpenShift-EDA (9.2*) is a strong foundational guide limited only by its deliberately basic immediate outcome
- EDB (8.7) remains a reference-grade VM-based DR architecture; AI Infrastructure (7.3) and RHAIIS (6.9*) need framework alignment work before they can compete with the top tier
- PostgreSQL Autovacuum Tuning is published but pending its first scored review