marcel/familienarchiv
1
0
Fork 0
Code Issues 117 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

docs(legibility): write 18 README.md files for canonical domain packages (DOC-6) #437

New Issue
Closed
opened 2026-05-05 21:08:46 +02:00 by marcel · 1 comment
marcel commented 2026-05-05 21:08:46 +02:00
Owner
Copy Link

Part of #394 (Epic 2 — Documentation). Rubric check: C7.1 (Major). Per #394 Decision Queue D2: enumeration is 18 files (not the original "~14" estimate), driven by the actual code on main and the Canonical Domain Set.

Problem

Anja, navigating the codebase, opens backend/src/main/java/.../document/ — there's no README, only Java files. She doesn't know the domain's boundaries until she reads every file. Per-domain READMEs compress the "what does this own" mental model into something readable in 30 seconds. Per Markus, every README uses a fixed 3-section template — anything longer becomes a maintenance burden.

Scope (18 files)

Backend (backend/src/main/java/org/raddatz/familienarchiv/) — 9 files

  1. document/README.md (covers annotation/, comment/, transcription/ sub-packages inline per Boundary decisions D-OQ-2/3/4)
  2. person/README.md (covers relationship/ sub-package inline per D-OQ-7)
  3. tag/README.md
  4. user/README.md
  5. geschichte/README.md
  6. notification/README.md (per D-OQ-6)
  7. ocr/README.md (per D-OQ-5)
  8. audit/README.md (cross-cutting but with domain footprint per D-OQ-8)
  9. dashboard/README.md (Tier-2 derived per D-OQ-8)

Frontend (frontend/src/lib/) — 8 files

  1. document/README.md
  2. person/README.md (per D-FE-1: PersonTypeahead/MultiSelect live here)
  3. tag/README.md (per D-FE-2)
  4. user/README.md
  5. geschichte/README.md
  6. notification/README.md
  7. ocr/README.md
  8. shared/README.md — admission criteria + the discussion/ sub-package per D-FE-3 + the dashboard/ sub-package per D-FE-4

OCR service — 1 file

  1. ocr-service/README.md — per Tobias: must include startup behaviour ("the service takes 30–60 seconds to become healthy on cold start due to model loading"), /health endpoint, and the X-Training-Token requirement.

Skipped — content lives in CONTRIBUTING.md (DOC-4)

Cross-cutting infrastructure with no domain identity: backend config/, exception/, security/, filestorage/, importing/. Their conventions are documented in walkthroughs, not standalone READMEs.

Fixed README template (per Markus — exactly 3 sections)

# <Domain name>

## What this domain owns
<entities, behaviours, side effects this domain is responsible for — bullet list>

## What it exposes
<public API: controller endpoints / Svelte components / module exports — bullet list>

## What it depends on
<other domains / shared/ / external services — bullet list>

Each section is short. Maintenance burden = number of facts × frequency of change. The 3-section template caps the burden.

References

Acceptance criteria

  • All 18 README.md files exist with the fixed 3-section template.
  • Anja-persona test: stranger opens backend/.../document/ and within 30 seconds knows what the domain owns and where to look for related files.
  • Cross-stack symmetry: backend document/README.md and frontend lib/document/README.md describe the same domain (same name, complementary perspectives).
  • OCR-service README includes the cold-start warning and X-Training-Token requirement.
  • No README is longer than ~50 lines (the 3-section template caps length).
  • Rubric C7.1 PASS verified by reviewer.

Definition of Done

All 18 READMEs are on main. Cross-stack symmetry verified by spot-checking document/, person/, tag/. Rubric C7.1 PASS.

Part of #394 (Epic 2 — Documentation). Rubric check: C7.1 (Major). Per #394 Decision Queue **D2**: enumeration is **18 files** (not the original "~14" estimate), driven by the actual code on `main` and the Canonical Domain Set. ## Problem **Anja**, navigating the codebase, opens `backend/src/main/java/.../document/` — there's no README, only Java files. She doesn't know the domain's boundaries until she reads every file. Per-domain READMEs compress the "what does this own" mental model into something readable in 30 seconds. Per Markus, every README uses a fixed 3-section template — anything longer becomes a maintenance burden. ## Scope (18 files) ### Backend (`backend/src/main/java/org/raddatz/familienarchiv/`) — 9 files 1. `document/README.md` (covers `annotation/`, `comment/`, `transcription/` sub-packages inline per Boundary decisions D-OQ-2/3/4) 2. `person/README.md` (covers `relationship/` sub-package inline per D-OQ-7) 3. `tag/README.md` 4. `user/README.md` 5. `geschichte/README.md` 6. `notification/README.md` (per D-OQ-6) 7. `ocr/README.md` (per D-OQ-5) 8. `audit/README.md` (cross-cutting but with domain footprint per D-OQ-8) 9. `dashboard/README.md` (Tier-2 derived per D-OQ-8) ### Frontend (`frontend/src/lib/`) — 8 files 10. `document/README.md` 11. `person/README.md` (per D-FE-1: PersonTypeahead/MultiSelect live here) 12. `tag/README.md` (per D-FE-2) 13. `user/README.md` 14. `geschichte/README.md` 15. `notification/README.md` 16. `ocr/README.md` 17. `shared/README.md` — admission criteria + the `discussion/` sub-package per D-FE-3 + the `dashboard/` sub-package per D-FE-4 ### OCR service — 1 file 18. `ocr-service/README.md` — per Tobias: must include startup behaviour ("the service takes 30–60 seconds to become healthy on cold start due to model loading"), `/health` endpoint, and the `X-Training-Token` requirement. ### Skipped — content lives in CONTRIBUTING.md (DOC-4) Cross-cutting infrastructure with no domain identity: backend `config/`, `exception/`, `security/`, `filestorage/`, `importing/`. Their conventions are documented in walkthroughs, not standalone READMEs. ## Fixed README template (per Markus — exactly 3 sections) ```markdown # <Domain name> ## What this domain owns <entities, behaviours, side effects this domain is responsible for — bullet list> ## What it exposes <public API: controller endpoints / Svelte components / module exports — bullet list> ## What it depends on <other domains / shared/ / external services — bullet list> ``` Each section is short. Maintenance burden = number of facts × frequency of change. The 3-section template caps the burden. ## References - Parent: #394 - Rubric: C7.1 - Inputs: Canonical Domain Set + Boundary decisions (#387 first comment) ## Acceptance criteria - [ ] All 18 README.md files exist with the fixed 3-section template. - [ ] **Anja-persona test**: stranger opens `backend/.../document/` and within 30 seconds knows what the domain owns and where to look for related files. - [ ] **Cross-stack symmetry**: backend `document/README.md` and frontend `lib/document/README.md` describe the same domain (same name, complementary perspectives). - [ ] OCR-service README includes the cold-start warning and `X-Training-Token` requirement. - [ ] No README is longer than ~50 lines (the 3-section template caps length). - [ ] Rubric C7.1 PASS verified by reviewer. ## Definition of Done All 18 READMEs are on `main`. Cross-stack symmetry verified by spot-checking `document/`, `person/`, `tag/`. Rubric C7.1 PASS.
marcel added this to the (deleted) milestone 2026-05-05 21:08:46 +02:00
marcel added the P1-highdocumentationlegibility labels 2026-05-05 21:08:52 +02:00
marcel commented 2026-05-05 21:14:23 +02:00
Author
Owner
Copy Link

Duplicate of #400. I created this in error before noticing #400 already existed. #400 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.

**Duplicate of #400.** I created this in error before noticing #400 already existed. #400 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.
 P1-high
Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.
 P2-medium
Noticeable improvement; doesn't block anything; schedule opportunistically.
 P3-later
Cosmetic or parking-lot work; fine to stay open indefinitely.
 audit
Read-only audit / assessment work; produces a report rather than changing code
 bug
Something isn't working
 cleanup
Removal of dead code, vague comments, naming violations, and scratch artifacts
 collaboration
We want to extend the family archive to have more collaboration tools
 conversation
descoped
We will do that later
 devops
documentation
README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs
 epic
Marker for epic-level issues that group multiple child issues
 feature
file-upload
legibility
Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction
 notification
person
phase-1: security
Security hygiene — must be done first
 phase-2: container-images
Production-ready multi-stage Docker images
 phase-3: prod-compose
Production compose overlay + Caddy reverse proxy
 phase-4: spring-prod-profile
Spring Boot production configuration profile
 phase-5: backups
Database and object storage backup strategy
 phase-6: deployment-docs
.env.example, DEPLOYMENT.md, runbook
 phase-7: monitoring
Prometheus, Loki, Grafana, Alertmanager
 refactor
Code restructuring without behaviour change
 security
test
ui
UI/UX and accessibility issues
 user
No Label P1-high documentation legibility
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Jens marcel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: marcel/familienarchiv#437
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?