Write user and operator documentation #52

New issue

Open

opened 2026-07-28 04:59:58 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-28 04:59:58 +00:00

Context

Documentation has grown alongside the code as design specs and a developer-oriented
README. Nobody has yet written the documentation for the person who simply wants to use
Circa to date their family photographs â€” and for a tool whose users are family members
rather than engineers, that gap matters.

Scope

User-facing and operator-facing documentation for the complete feature set.

Implementation notes

User guide covering the full workflow: scanning, ingest, review, resolving duplicates
and disputes, and export. Written for a non-technical family member.
Explain the concepts the UI assumes: evidence versus decision, precision and ranges, why
a derived date is a suggestion rather than a fact. These ideas are the heart of the
product and are currently only documented in an engineering spec.
Operator guide: installation, configuration reference, backup and restore, upgrades,
and troubleshooting.
Reconcile the design specs in docs/ with what was actually built. Several were written
before implementation and will have drifted; documentation that contradicts the software
costs more than none.
Configuration reference generated from or verified against the settings code, so it
cannot silently go stale.
Screenshots of the real UI, with a note on keeping them current.
Update README.md to be a genuine front door, and confirm AGENTS.md reflects how the
project actually works now â€” including that issues and milestones live in Forgejo.

Done when

A non-technical user can follow the guide from scanning to export
The operator guide covers install, config, backup, restore, upgrade, and troubleshooting
Design specs are reconciled with the implementation
The configuration reference is verified against the code
README and AGENTS.md are current

References

docs/, README.md, AGENTS.md

## Context Documentation has grown alongside the code as design specs and a developer-oriented README. Nobody has yet written the documentation for the person who simply wants to use Circa to date their family photographs â€” and for a tool whose users are family members rather than engineers, that gap matters. ## Scope User-facing and operator-facing documentation for the complete feature set. ## Implementation notes - User guide covering the full workflow: scanning, ingest, review, resolving duplicates and disputes, and export. Written for a non-technical family member. - Explain the concepts the UI assumes: evidence versus decision, precision and ranges, why a derived date is a suggestion rather than a fact. These ideas are the heart of the product and are currently only documented in an engineering spec. - Operator guide: installation, configuration reference, backup and restore, upgrades, and troubleshooting. - Reconcile the design specs in `docs/` with what was actually built. Several were written before implementation and will have drifted; documentation that contradicts the software costs more than none. - Configuration reference generated from or verified against the settings code, so it cannot silently go stale. - Screenshots of the real UI, with a note on keeping them current. - Update `README.md` to be a genuine front door, and confirm `AGENTS.md` reflects how the project actually works now â€” including that issues and milestones live in Forgejo. ## Done when - [ ] A non-technical user can follow the guide from scanning to export - [ ] The operator guide covers install, config, backup, restore, upgrade, and troubleshooting - [ ] Design specs are reconciled with the implementation - [ ] The configuration reference is verified against the code - [ ] README and AGENTS.md are current ## References - `docs/`, `README.md`, `AGENTS.md`

claude-bot added this to the v1.0.0 milestone

2026-07-28 04:59:58 +00:00

claude-bot added the

docs

label

2026-07-28 04:59:58 +00:00