Why Architecture Decision Records keep teams from re-litigating settled choices — what to capture, how to structure an ADR, where to store them, and how to make them documents engineers actually read and reference.
Documentation
-
ADRs in Practice: Architecture Decision Records That Teams Actually Read -
Diátaxis for Technical Writing: The Framework Behind Great Docs The Diátaxis framework that fixes most broken documentation — separating tutorials, how-to guides, reference, and explanation — and why mixing those four modes on one page is why users skim, give up, and file issues the docs already answer.
-
Developer Portals with Backstage: Catalog, Scaffolding, TechDocs, and Plugins A practical guide to Backstage — setting up the software catalog, creating service templates for self-service scaffolding, writing TechDocs, building plugins, and deploying Backstage to Kubernetes.
-
OpenAPI and Swagger: Designing and Documenting APIs Contract-First Learn how to design and document APIs contract-first using the OpenAPI Specification — covering document structure, schemas, security, code generation, and the full tooling ecosystem from Swagger UI to Prism mock servers.
-
Writing Good READMEs: Documentation That Developers Actually Read A practical guide to writing READMEs that developers actually read — covering structure, examples, anti-patterns, and templates for open-source and internal projects alike.
-
Technical Writing for Developers Writing documentation, READMEs, and technical content that people actually read.