Engineering Documentation & ADRs

An ADR habit, design document and README standards, runbooks people can follow, and the review rhythms that keep engineering knowledge current after people move on or forget.

Free · Mac (Apple silicon) and Windows · v1.0.5 · Other platforms

Then open the Marketplace in the app, search for Engineering Documentation & ADRs, and click Install. It goes into your own files, and works offline from then on.

What it installs.

1

Pillar

1

Area

50

Projects

200

Starter tasks

⚙️ Software Engineering

Engineering Documentation & ADRs

Keeping design documents, architecture decision records, READMEs and runbooks current so knowledge survives people leaving or forgetting.

  1. Documentation inventory and ownership map
  2. Deciding where engineering docs live
  3. ADR template and numbering convention
  4. Backfilling ADRs for decisions already made
  5. README standard for every repository
  6. Design document template with review states
  7. Docs-as-code setup in the main repository
  8. Owner and review date on every page
  9. Runbook template for operational tasks
  10. Glossary of system and domain terms
  11. Definition of done that includes documentation
  12. Weekly triage of proposed ADRs
  13. Monthly stale page sweep
  14. Quarterly runbook walk-through
  15. Documentation prompt in the pull request template
  16. Broken link and dead reference checks
  17. Weekly design doc review slot
  18. Documentation debt backlog
  19. Quarterly README audit across repositories
  20. Yearly documentation ownership refresh
  21. Writing ADR context and consequences well
  22. Plain technical writing for engineers
  23. Diagrams as code with the C4 model
  24. Writing runbook steps for the 3am reader
  25. Structuring docs with the Diataxis framework
  26. Writing alternatives considered honestly
  27. Reviewing and editing a colleague's document
  28. Code comments versus external docs
  29. Choosing a docs site generator or wiki platform
  30. Docs search that engineers actually use
  31. Superseding and revisiting old ADRs
  32. Which decisions deserve an ADR
  33. Migrating a legacy wiki into docs-as-code
  34. Generated reference for config flags and CLI commands
  35. Reader feedback on documentation pages
  36. Pruning and archiving obsolete documentation
  37. One-page system overview for the codebase
  38. Knowledge capture before a key engineer leaves
  39. Team documentation day
  40. Documentation pack for an audit or due diligence
  41. Documentation handover to another team
  42. Launch documentation pack for a new service
  43. Lightweight ADRs for a solo or two-person team
  44. Docs habits for a team with no technical writer
  45. Async decision records for a distributed team
  46. Documenting an inherited codebase with no docs
  47. Documentation freshness metrics
  48. Prose linting with a docs style checker
  49. Cross-repository ADR index and decision search
  50. AI-assisted doc drafting with human review rules

Where it starts.

Each project arrives with its purpose, milestones and first tasks written out. Here is how the first three read.

Documentation inventory and ownership map

This is a team plan, best installed into a shared workspace so everyone with a role in it can see and own their tasks. Most teams have docs scattered across a wiki, repository READMEs, shared drives and chat threads, and nobody can say which ones are current.

First tasks

  • Create an inventory sheet with columns for location, type, owner and last update
  • List every wiki space, repository and shared folder that holds engineering docs
  • Ask the team which five documents they open most often
  • Flag every page with no owner or no edit in the last twelve months

Deciding where engineering docs live

Engineers stop looking for documentation once they have been burned by finding three conflicting versions in three tools. Deciding which kinds of document live in the repository beside the code and which live in a wiki, and writing that rule down, ends the question for every future page.

First tasks

  • List the kinds of engineering document the team writes today
  • Propose a home for each type with a one-line reason
  • Agree the rule with the team in the next planning meeting
  • Add a pointer on each old location to the new home

ADR template and numbering convention

An architecture decision record is only useful if the next one looks like the last one, so readers know where to find the context, the decision and the consequences. Settling the template, file naming, numbering and status values once makes writing an ADR a fifteen-minute job instead of a formatting debate.

First tasks

  • Read two published ADR formats and note what each section is for
  • Draft the team's template with status, context, decision and consequences
  • Agree the file naming and numbering rule
  • Commit the template and a short how-to to the decisions folder

Make it yours.

Install Engineering Documentation & ADRs, then tell Aurum the date you're aiming for. It checks whether the plan fits the weeks you actually have.

Free · Mac (Apple silicon) and Windows · v1.0.5 · Other platforms

Blueprints are general information to help you organise your own work. They are not medical, financial, legal or other professional advice. See the Terms.