Architecture & quality assessments

Overview

These pages are maturity assessments for this repo. Each report lists reference practices (Table 1), scores how we match them (Table 2) with a short justification per row, then scoring arithmetic, Top‑5 gaps with workflow status (TODO / IN PROGRESS / DONE), and next steps. ADRs record decisions; assessments record how we compare to common practice on a given date.

Format and location

Unified template: docs/audit/AUDIT_TEMPLATE.html — use <section id="overview" class="card"> for metadata (do not use class="lead" on a top paragraph). Table 2 uses the shared score legend and optional pre.audit-scoring-formula plus table.audit-gap-table for Top‑5 tracking (see ADR 0024).

Layout: assessments are grouped by type:

docs/audit/docs/ — documentation / DX assessments.
docs/audit/api/ — REST / HTTP API assessments.

File names may use YYYY-MM-DD-topic-assessment.html or stable names under each folder; the assessment date belongs in Overview and document history.

How to create assessments (naming, structure, prompt)

File naming and location

Preferred file name: YYYY-MM-DD-topic-assessment.html — date first (ISO), then kebab-case topic, then -assessment.html. Example: 2026-04-23-ui-ux-assessment.html.
Folder: put the file under the right type: docs/audit/docs/ (documentation / DX / UI of docs) or docs/audit/api/ (REST / HTTP API). Do not place new assessments in docs/audit/ root unless you are updating the template itself.
Title alignment: the same formation date must appear in <title>, <h1>, Overview, and the first “Page history” row where applicable (see comment in AUDIT_TEMPLATE.html).
Asset paths: for pages inside docs/audit/docs/ or docs/audit/api/, link shared CSS/JS with ../../assets/… (two levels up to docs/assets/).
Index: add a row to the matching index (docs/audit/docs/README.html or docs/audit/api/README.html) and record the change in that page’s Page history.

Required HTML structure (must match the repo template)

Copy docs/audit/AUDIT_TEMPLATE.html and replace placeholders. Do not invent a different section order or skip numbered sections. Minimum skeleton:

<body data-maintainer-ids="…"> — maintainer person id(s) for Page editors.
<main class="container"> with <h1>, <div id="docs-top-nav"></div>, <div id="docs-page-meta-mount" hidden></div>.
<section id="overview" class="card"> — Overview.
<h2 id="1-scope-and-methodology"> — Scope and methodology (subsections as needed).
<h2 id="table-1-reference-practices"> — Table 1 in table.audit-ref-table (reference practices).
<h2 id="table-2-study-app-scores"> — Table 2 in table.audit-score-table, score cells td.score-excellent|score-good|score-needs-attention, plus <div class="audit-score-legend-include" data-legend-id="…"></div> and <noscript> legend fallback per template.
<h2 id="4-scoring-summary"> — §4.1 narrative, §4.2 optional weighted model, §4.3 Top five gaps in table.audit-gap-table with status cells audit-gap-status--todo|inprogress|done.
<h2 id="5-page-history"> — numbered “5. Page history” table, plus the duplicate <section id="page-history" class="card"> block as in the template (repository convention).
<div class="docs-inpage-toc-mount" data-inpage-toc="auto"></div> before </main>.

Score scale and governance: ADR 0024. Broader HTML rules: Documentation style guide.

LLM prompt — generate a new assessment (copy/paste)

Paste into your assistant. Replace bracketed fields. Output must be a single valid HTML file matching the structure above, saved under the correct docs/audit/… folder with the correct file name.

You are a technical writer and quality auditor for the Study App repository.

              Task: produce a new maturity assessment page as HTML only.

              Hard requirements:
              1) Follow the exact section order and heading ids from docs/audit/AUDIT_TEMPLATE.html (Overview; 1. Scope; 2. Table: Reference practices; 3. Table: AS-IS situation; 4. Scoring summary with subsections 4.1–4.3; 5. Page history; duplicate section id="page-history"; docs-inpage-toc-mount at end of main).
              2) Use table.audit-ref-table for Table 1, table.audit-score-table for Table 2 with justification column, audit-score-legend-include + noscript fallback, table.audit-gap-table for Top five gaps.
              3) Use body data-maintainer-ids="16fc8b78537109162984a2fdbef6e142" unless the user specifies another id.
              4) For a file saved under docs/audit/docs/ or docs/audit/api/, use relative paths ../../assets/docs.css, ../../assets/docs-theme.css, ../../assets/docs-nav.js, ../../assets/docs-portal-data.js, ../../assets/docs-internal-meta.js, and ../../assets/favicon.svg.
              5) File name: YYYY-MM-DD-<topic>-assessment.html. Put the same formation date in <title>, <h1>, and Overview.
              6) Language: English. No markdown — output raw HTML only.

              Context for this assessment:
              - Assessment type: [docs/DX vs REST API — pick one]
              - Topic: [short name]
              - Formation date (YYYY-MM-DD): [date]
              - Table 1 rows: [number and themes — or “match existing DX/API audit row count in the sibling assessment file”]
              - Evidence to cite: [paths, ADRs, Makefile targets, OpenAPI, etc.]
              - Top five gaps to track: [list]

              Deliver: the full HTML document, nothing else.

Industry context

Large firms often use design reviews, launch checklists, security programs, and central dev portals. Here we use a smaller, git-based version: Table 1 (what “good” looks like), Table 2 (our scores), then gaps and fixes. Same general idea as big-company reviews; it does not replace tests, ADRs, or formal sign-off.

Unless stated, assessments assume PET-scale work. A low score often means “not done yet” or “not worth it at this size,” not “you must build an enterprise portal.” See ADR 0024 — industry context.

All published assessments

Assessment type	Focus
Documentation Experience (DX)	Gap assessment for documentation experience (DX), including UI/UX audit templates and assessments.
REST API	Gap assessment for REST API

Note changes in docs/CHANGELOG.md.

Page history

Date	Change	Author
2026-04-22	Added “How to create assessments” (naming, required structure, LLM copy/paste prompt).	Ivan Boyarkin
2026-04-21	Added direct link card for latest UI/UX assessment page.	Ivan Boyarkin
2026-04-21	Updated Documentation Experience row to reflect UI/UX assessments under `docs/audit/docs/`.	Ivan Boyarkin
2026-04-21	Added Page history section (repository baseline).	Ivan Boyarkin