motief/docs/plans/2026-04-24-004-rewrite-readme-plan.md

title	type	status	date
docs: Rewrite README.md with quickstart and project overview	feat	active	2026-04-24

Rewrite README.md

Overview

The current README.md is 22 lines and only covers embeddings and Ansible deployment. It does not explain what Stemwijzer is, how to run it locally, or how to run the pipeline. New contributors must discover ARCHITECTURE.md to get oriented.

Problem Frame

• README is the first file a visitor sees
• No quickstart instructions
• No mention of Streamlit, the voting UI, or the explorer
• No screenshot or demo link
• Missing prerequisites (Python 3.13, uv, DuckDB)

Requirements Trace

• R1. Explain what the project does in 2 sentences
• R2. Show a screenshot or demo link
• R3. List prerequisites and installation steps
• R4. Provide quickstart commands (run app, run pipeline, run tests)
• R5. Link to ARCHITECTURE.md for deep dive
• R6. Link to docs/ for additional documentation

Scope Boundaries

Included:

• Rewrite README.md with new structure

Excluded:

• Changing ARCHITECTURE.md (only link to it)
• Adding screenshots (placeholder path accepted)
• Creating a demo deployment

Key Technical Decisions

• Keep it concise — README should be scannable in 2 minutes. Deep content lives in ARCHITECTURE.md.
• Use the same commands as ARCHITECTURE.md — single source of truth for commands
• Match the project's language — Dutch UI, English docs

Implementation Units

• U1. Draft and review README structure

Goal: Create a README that a new contributor can follow to get the app running in <10 minutes.

Requirements: R1–R6

Dependencies: None

Files:

• Modify: README.md

Approach: Structure:

1. Title + one-line description
2. Screenshot placeholder
3. What is Stemwijzer? (2 sentences)
4. Features bullet list (voting compass, explorer, analytics)
5. Prerequisites (Python 3.13, uv)
6. Quickstart (clone, uv sync, run Streamlit, run pipeline)
7. Testing (uv run pytest)
8. Project structure (brief, link to ARCHITECTURE.md)
9. Documentation links (ARCHITECTURE.md, docs/)
10. License

Test expectation: none — documentation-only change. Verify by reading the rendered markdown.

Verification:

• A new contributor can follow the quickstart without reading other files
• All commands in README match ARCHITECTURE.md
• No broken internal links

---

Risks & Dependencies

Risk	Mitigation
README grows too long	Cap at ~80 lines; defer deep content to ARCHITECTURE.md
Commands become outdated	Cross-check against ARCHITECTURE.md before finalizing

Documentation / Operational Notes

• This is the documentation change. No other docs need updating.

Sources & References

• Existing README: README.md
• Deep docs: ARCHITECTURE.md
• Code style: CODE_STYLE.md