[gino-m]

Collect One review series: D1 Docs: product & UX (2/60)

Tracking issue: #2629 · Stacked on: c1 (C01 #2630 merged) · Reviewer: @rfontanarosa
FYI: @gino-m @shobhitagarwal1612

Context

Collect One is the Kotlin Multiplatform successor to Ground: a single shared codebase for the web console, the mobile app (Android, iOS, browser), and a Spanner-backed user-data service. Forms use ProtoForms, a lossless proto3 encoding of ODK XForms.

This PR is one slice of the frozen wip/baobab tree (collect-one-review-base), landing through 60 stacked PRs into c1 (see #2629). It adds the core product specifications, partner integration architecture, terminology lexicon, and UX guidelines. Stacked on c1 (now that C01 #2630 is merged), so the diff shows only this slice.

What's in this PR

• docs/README.md: Index of Collect One architecture, design specs, and data model documentation across product, technical, and UX sections; core mental model (Entity-only map, 1-Form-to-1-Entity provisioning, live schema sync).
• docs/product/prd.md: Comprehensive Product Requirements Document covering mission, multiplatform reach (Web, Android, iOS), desk-to-field loop uniting CEO and Ground, XLSForm/ODK Entities compliance, feature matrix, and functional requirements.
• docs/product/concept-brief.md: Executive summary of why FAO, SIG, and Google are uniting Ground and CEO; problem statement, target personas, scope boundaries, and institutional roles.
• docs/product/ceo-integration.md: Collect Earth Online functional inventory and desk-to-field plot flagging architecture (multi-temporal satellite visual interpretation, blind consensus QA/QC, high-uncertainty field routing).
• docs/product/xforms-integration.md: XForms and ODK Entities integration architecture; the Entity-only map model, default 1-Form-to-1-Entity provisioning, and automatic save_to schema synchronization.
• docs/product/terminology.md: Master terminology lexicon and cross-platform parity matrix across Collect One, Collect Earth Online, ODK Central/Collect, KoboToolbox, XLSForm, ArcGIS Survey123, and Open Foris Arena.
• docs/product/impact-measurement.md: Proposed MAP (Mitigation, Adaptation, Protection) impact measurement approach with minimal field burden (Purpose Packs, semantic indicator tags, spatial overlays, outcome events, partner ledgers, and attribution rubric).
• docs/product/impacts.md: Global impact analysis, deployment case studies, and field metrics across Ghana, Burundi, Kenya, and Viet Nam.
• docs/product/website-outline.md: Public documentation and portal structure.
• docs/product/future-work.md: Extensibility roadmap, future integrations, and post-C1 evolution.
• docs/ux/content-guidelines.md: UX writing standards, voice and tone, domain terminology, and content principles for user-facing copy.

Where it fits

Foundational product and architectural reference for the entire repository. Later slices—protos (P1–P3), core engine (K1–K7), UI (U1–U2), server (S1–S4), web (W1–W10), mobile (MB1–MB2), and hosts (H1–H3)—implement the data models, workflows, and terminology defined here.

Not in this PR

• ProtoForms specification and technical data models → D2 ([Collect One 8/60] Docs: forms data model (D2) #2634), D3
• Client/backend architecture and sync engine docs → D4
• Proto schemas → P1–P3; Kotlin modules → K*, U*, M1, A*, W*, MB*; server → S1–S4; hosts → H1–H3

Suggested reading order

1. docs/product/concept-brief.md (orientation and institutional partnership)
2. docs/product/prd.md (complete product requirements and platform capabilities)
3. docs/product/xforms-integration.md and docs/product/terminology.md (core mental model and terminology mapping)
4. docs/product/ceo-integration.md (desk-to-field workflow loop)
5. docs/ux/content-guidelines.md and docs/product/impact-measurement.md

Focus areas

• The Entity-only map model and automatic 1-Form-to-1-Entity provisioning (xforms-integration.md): does this cleanly bridge simple surveys with longitudinal multi-visit monitoring?
• Terminology harmonization (terminology.md): does the cross-platform parity matrix accurately align with ODK, XLSForm, CEO, and Arena conventions?
• Desk-to-field integration (ceo-integration.md): clarity of the handoff between satellite visual interpretation and offline ground verification.

Safe to skim

• docs/product/website-outline.md and docs/product/future-work.md (introductory portal outline and future roadmap)

Size

Source	Tests	Data	Files
2,419 (Markdown)	0	0	11

Testing

Docs only. Verified formatting and licenses via ./c1q.py verify D1 (ktfmt: PASS, license: PASS). CI: check (ktfmt, buf).
Checked for published monetary amounts (git grep -nE '(\$|€|£|USD|EUR) ?[0-9]'): 0 occurrences found.

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation for Open Foris Collect One, detailing its product requirements, integration with Collect Earth Online, terminology parity, XForms integration, and impact measurement framework. The documentation is well-structured and thorough. The review feedback highlights a few minor areas for improvement, including correcting a typo ('exclusivamente' to 'exclusively'), standardizing punctuation and placeholder brackets, ensuring consistent naming for 'FAO GEF 7', and refining some awkward phrasing in the XForms integration guide.