[markbac]

Moves the templates and checklists into content/templates/ (document templates): one merged set of checklists, written as task lists, and one set of templates. The files that tools read are in content/templates/files/.

⚠️ Needs a one-line change outside this section

The section doesn't appear on either site at the moment, and that's true on main too. MkDocs always excludes a top-level templates/ folder from docs_dir (its built-in exclude_docs default is .* plus /templates/), so site/docs/templates/ is written but never built. That's why there's no site/build/templates/, and no warning either. I tested this fix locally and then reverted it, because site/mkdocs.yml is outside my scope:

# site/mkdocs.yml, after docs_dir: docs
exclude_docs: |
  !/templates/

With this line, py-doc site build makes templates/ on both sites. All internal links and diagrams resolve, and the home page shows the card. The other way round it would be to rename the document key (for example to checklists), which changes the URLs.

Checks

• py-doc lint content/templates --strict: 0 warnings or errors (Vale 3.15.2, en-GB). 200 info notes remain, mostly passive voice and the checklist ID prefixes (see acronyms below).
• py-doc build templates: build/templates.docx and build/templates.pdf, 40 pages, every figure and table captioned. Checklists come out as ☐ bullets in Word and PDF.
• py-doc site build: succeeds. With the exclude_docs line above, the section is on both sites.
• py-doc c4 check on files/c4-workspace.dsl: 0 errors. The commit-msg hook was tested against valid and invalid headers, merge/fixup commits and REQUIRE_REFS.

Provenance

New file	From
index.md	New (section overview, lists of checklists, templates and downloads)
definition-of-ready.md	site-web-content-src Templates/src/Checklists/dor.md + technical-documentation docs/guidelines/GU-004-definition_of_ready_guide.md
definition-of-done.md	Checklists/dod.md + GU-003-definition_of_done_guide.md
architecture-review-checklist.md	Checklists/architectureChecklist.md + GU-018-architecture_review_checklist.md (process, rubric, review record)
design-review-checklist.md	Checklists/designChecklist.md + GU-001-design_checklist_guide.md
code-review-checklist.md	Checklists/codeReview.md (incl. its defensive-coding list, which GU-002 had dropped) + GU-002-code_review_checklist.md
debugging-checklist.md	Checklists/debugging.md + GU-021-defect_management_and_debugging.md §3
defect-report-checklist.md	Checklists/defects.md (creation and resolution rules) + GU-021 §1–2 (report template, example, severity and priority)
adr.md	EngineeringProcess docs/templates-reference/adr.md + GU-005 template fields + Example-Repo C4/adrs/0001-record-architecture-decisions.md (its Nygard link, updated)
rfc.md	templates-reference/rfc.md + GU-006 template fields
requirements.md	templates-reference/requirement.yaml + templates-reference/nfr-scenario.md
interface-specification.md	templates-reference/interface-specification.md (condensed)
architecture-document.md	Example-Repo docs/Project/Architecture (arc42), rewritten as an outline in my own words with links to arc42; new C4-PlantUML and Structurizr starters replacing technical-documentation/templates/*.puml
architecture-canvases.md	Example-Repo docs/Project/Communication and docs/Project/Inception
experiment-record.md	templates-reference/experiment-record.md
postmortem.md	templates-reference/postmortem.md + GU-021 §4 (five whys, fishbone, blameless template)
pull-request-and-commits.md	templates-reference/pull-request-template.md + Example-Repo README.md (Conventional Commits) and .githooks/commit-msg
agent-task-brief.md	templates-reference/agent-task-brief.md
product-conformance-profile.md	templates-reference/product-conformance-profile.md + templates-reference/component-register.yaml
files/requirement.yaml, files/component-register.yaml	EngineeringProcess templates-reference/ (comments and a licence field added)
files/commit-msg	New POSIX sh hook, replacing Example-Repo's bash hook
files/c4-workspace.dsl	New
files/architecture-*-canvas.{drawio,pptx}	Example-Repo canvases (CC BY-SA 4.0, arc42), unchanged except one stray asdf label removed from the communication canvas
files/NOTICE	New: licence of the canvases versus the rest

Dropped, and why

• "Good code v bad code" cartoon (Checklists/media/image1.jpg): it's someone else's drawing.
• Severity/priority prose and images in defects.md (media/image2-4.png, the "Bug Severity vs Priority" text and the LambdaTest link): copied from a vendor blog. It's replaced by my own severity and priority tables, based on GU-021.
• The healthcare defect example in defects.md: replaced by GU-021's embedded example, rewritten.
• Verbatim arc42 template (Architecture/template.md and 01–12_*.md, the arc42 images): it's the arc42 authors' text. It's replaced by a summary of the 12 sections in my own words, with links to arc42.org and docs.arc42.org.
• technical-documentation/templates/C4*.puml: vendored copies of the C4-PlantUML library (v2.13.0), not starter files. PlantUML's standard library includes C4, so the starters use !include <C4/...>.
• Template-version_git.docx, Template.pptx: Word/PowerPoint styles for the old build. py-doc has its own.
• Example-Repo C4/workspace.dsl and C4/docs: Simon Brown's Financial Risk System kata, not ours. A new starter workspace replaces it.
• Example-Repo ACC.md (Marp's sample deck), Overview*, SolutionArchitectureGuide.pptx, media/, Untitled diagram*, example.bpmn: not templates. They're out of scope for this section and left for whoever reviews the archive.
• The bash hook's JIRA-n|NO-JIRA requirement: replaced by an optional Refs: trailer (REQUIRE_REFS=1), which matches the PR template.
• The "one exit point" rule as a universal rule: kept only "where the coding standard requires it" (MISRA C).
• GU-001/002/003/004/018/021 framing prose (purpose lists, "keep it living" and similar): trimmed to the parts that help someone use the checklist.

Old URLs to redirect

For plugins.redirects.redirect_maps in site/mkdocs.yml (paths relative to docs_dir):

Templates/index.md: templates/index.md
Checklists/index.md: templates/index.md                       # tarf.co.uk/Checklists was a 404
Templates/Checklists/checklists/index.md: templates/index.md
Templates/Checklists/architectureChecklist/index.md: templates/architecture-review-checklist.md
Templates/Checklists/codeReview/index.md: templates/code-review-checklist.md
Templates/Checklists/debugging/index.md: templates/debugging-checklist.md
Templates/Checklists/defects/index.md: templates/defect-report-checklist.md
Templates/Checklists/designChecklist/index.md: templates/design-review-checklist.md
Templates/Checklists/dod/index.md: templates/definition-of-done.md
Templates/Checklists/dor/index.md: templates/definition-of-ready.md

markbac.github.io/EngineeringProcess/templates-reference/… is served by the EngineeringProcess repo's own Pages site, so redirects here only take effect once that site is switched off:

EngineeringProcess/templates-reference/adr/index.md: templates/adr.md
EngineeringProcess/templates-reference/rfc/index.md: templates/rfc.md
EngineeringProcess/templates-reference/nfr-scenario/index.md: templates/requirements.md
EngineeringProcess/templates-reference/interface-specification/index.md: templates/interface-specification.md
EngineeringProcess/templates-reference/experiment-record/index.md: templates/experiment-record.md
EngineeringProcess/templates-reference/postmortem/index.md: templates/postmortem.md
EngineeringProcess/templates-reference/pull-request-template/index.md: templates/pull-request-and-commits.md
EngineeringProcess/templates-reference/agent-task-brief/index.md: templates/agent-task-brief.md
EngineeringProcess/templates-reference/product-conformance-profile/index.md: templates/product-conformance-profile.md

technical-documentation is private, and as far as I can tell it had no public URLs.

Acronyms for lint.acronyms.allowed

Optional, since they only show up as info. They'd cut the noise: the checklist ID prefixes ARC, SD, DBG, DC, DR, TST, SEC, DoR, DoD, plus RTOS, DMA, EEPROM, DSL, LED, IEC, ISO, MIT, AMQP, XML, POSIX.

Open questions for Mark

1. The exclude_docs line (above): add it to site/mkdocs.yml, or rename the document so the URL isn't /templates/?
2. Download links use https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/…, because py-doc only copies pictures onto the site, not other files a page links. They work once this is merged, and on both sites. Should py-doc copy linked non-picture files (a py-doc change), or are raw GitHub links fine?
3. Canvases: OK to redistribute the arc42 canvases (CC BY-SA 4.0, attributed in the page and files/NOTICE), or would you rather only link to canvas.arc42.org?
4. Overlap with Guidelines: GU-001/002/003/004/018/021 and GU-005/006 (the ADR and RFC authoring guides) are also in technical-documentation's guidelines. The Guidelines section should link to these pages rather than carry its own copies of the checklists and templates.
5. IDs: I kept the old IDs where items survived (ARC-1–23, SD-1–47, DoD/DoR, DC-n). The code review and debugging lists are renumbered, because merging changed their structure. Is that OK, or is anything referring to the old numbers?

🤖 Generated with Claude Code