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

docs(legibility): write human-targeted root README.md (DOC-1) #432

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

Part of #394 (Epic 2 — Documentation). Rubric checks: C1.1 (Critical), C1.2 (Major), C1.4 (Major).

Problem

A first-time visitor cloning the repo today sees no README at the root — only CLAUDE.md, CODESTYLE.md, COLLABORATING.md, docker-compose.yml. Anja (Backend Dev) and Tobias (PM-with-CS) have no front door. They do not know what Familienarchiv is, what it consists of, or where to go next. This is the first impression for every future evaluator and Successor-X.

Scope

  1. Create /README.md at the repo root.
  2. Sections in this order (max ~120 lines total — README is a launchpad, not a manual):
    • What is Familienarchiv — ≤3 sentences, audience: a stranger with a CS background.
    • Five components — frontend (SvelteKit 2 / Svelte 5), backend (Spring Boot 4 / Java 21), OCR service (FastAPI / Python 3.11), PostgreSQL 16, MinIO (S3-compatible). One-line description per component.
    • Three reader journeys (per Leonie's recommendation): "I want to run it locally" → quickstart, "I want to understand the system" → docs/ARCHITECTURE.md, "I want to contribute" → CONTRIBUTING.md.
    • See also — explicit cross-links to docs/ARCHITECTURE.md (#433), CONTRIBUTING.md (#435), docs/DEPLOYMENT.md (#436), Gitea issue tracker URL.
  3. Quickstart: a single docker compose up -d (or short numbered sequence) that brings the stack up — link to CONTRIBUTING.md for prerequisites.

References

Acceptance criteria

  • README.md exists at repo root.
  • Tobias-persona test: a stranger reads the README and can describe Familienarchiv's purpose in their own words after the first paragraph.
  • All 5 components named with one-line descriptions (rubric C1.2).
  • Three "See also" links present and resolve to existing files (rubric C1.4).
  • Rubric C1.1 PASS, C1.2 PASS, C1.4 PASS verified by reviewer.

Definition of Done

README is on main. Rubric checks C1.1, C1.2, C1.4 PASS in a follow-up audit (CLEANUP-5 / Epic 5).

Part of #394 (Epic 2 — Documentation). Rubric checks: **C1.1 (Critical)**, C1.2 (Major), C1.4 (Major). ## Problem A first-time visitor cloning the repo today sees no README at the root — only `CLAUDE.md`, `CODESTYLE.md`, `COLLABORATING.md`, `docker-compose.yml`. **Anja** (Backend Dev) and **Tobias** (PM-with-CS) have no front door. They do not know what Familienarchiv is, what it consists of, or where to go next. This is the first impression for every future evaluator and Successor-X. ## Scope 1. Create `/README.md` at the repo root. 2. Sections in this order (max ~120 lines total — README is a launchpad, not a manual): - **What is Familienarchiv** — ≤3 sentences, audience: a stranger with a CS background. - **Five components** — frontend (SvelteKit 2 / Svelte 5), backend (Spring Boot 4 / Java 21), OCR service (FastAPI / Python 3.11), PostgreSQL 16, MinIO (S3-compatible). One-line description per component. - **Three reader journeys** (per Leonie's recommendation): "I want to run it locally" → quickstart, "I want to understand the system" → `docs/ARCHITECTURE.md`, "I want to contribute" → `CONTRIBUTING.md`. - **See also** — explicit cross-links to `docs/ARCHITECTURE.md` (#433), `CONTRIBUTING.md` (#435), `docs/DEPLOYMENT.md` (#436), Gitea issue tracker URL. 3. Quickstart: a single `docker compose up -d` (or short numbered sequence) that brings the stack up — link to `CONTRIBUTING.md` for prerequisites. ## References - Parent: #394 - Inputs (read-only): #387 first comment (Project Brief, Personas) - Existing docs to link (not duplicate): `docs/ARCHITECTURE.md` (#433), `CONTRIBUTING.md` (#435), `docs/DEPLOYMENT.md` (#436), `docker-compose.yml` ## Acceptance criteria - [ ] `README.md` exists at repo root. - [ ] **Tobias-persona test**: a stranger reads the README and can describe Familienarchiv's purpose in their own words after the first paragraph. - [ ] All 5 components named with one-line descriptions (rubric C1.2). - [ ] Three "See also" links present and resolve to existing files (rubric C1.4). - [ ] Rubric **C1.1 PASS**, **C1.2 PASS**, **C1.4 PASS** verified by reviewer. ## Definition of Done README is on `main`. Rubric checks C1.1, C1.2, C1.4 PASS in a follow-up audit (CLEANUP-5 / Epic 5).
marcel added this to the Codebase Legibility milestone 2026-05-05 21:06:01 +02:00
marcel added the P0-criticaldocumentationlegibility labels 2026-05-05 21:06:08 +02:00
marcel commented 2026-05-05 21:14:15 +02:00
Author
Owner
Copy Link

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

**Duplicate of #395.** I created this in error before noticing #395 already existed. #395 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 P0-critical documentation legibility
Milestone
No items
No Milestone Codebase Legibility
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#432
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?