chore: update wordings

Author: tnagorra

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 .env
 _site
+.jekyll-metadata

docs/overview.md

@@ -6,14 +6,14 @@ permalink: /docs/overview/
 
 # MapSwipe Overview
 
-## A typical MapSwipe workflow
+This page walks through the typical MapSwipe workflow, from a project manager setting up a project through to volunteers contributing results and the data being exported. For how the underlying components fit together, see [System Architecture](/docs/system_architecture/).
 
-1. Project managers upload information about their projects (e.g. area of interest, objects to look for) to backend, which will sync information to Firebase in realtime database, using the **manager dashboard**.
-2. A tutorial must be attached to the projects using existing tutorials or a new one in the final phase of project creation before the publishing it.
-3. After the project is published from the **manager dashboard**, relevant groups and tasks are created in the backend and synced with Firebase
-4. The users of the MapSwipe app contribute to the projects and submit their results via app which will be stored in backend as well as Firebase realtime database. The **firebase rules** ensure, that app users can only change pre-defined parts of the firebase realtime database.
-5. Once new results are submitted, the **backend** and **firebase functions** generate real-time statistics and update the progress of groups, compute project level statistics and user statistics in the backend and firebase realtime database.
-6. All results are synchronized with **backend** and **firebase** on defined basis (e.g. every 10 minutes). The backend database holds all MapSwipe results for long term storage. Once results are synced in the backend database, they will be deleted in Firebase realtime database by the workers.
-7. Based on the data in the backend, the **backend** generates aggregated data and statistics (e.g. as CSV files). The data is served by the backend's GraphQL endpoint (the older nginx-served REST API is no longer used).
+## A typical MapSwipe workflow
 
-For the architectural picture behind this workflow — old vs. new architecture and the individual components — see [System Architecture](/docs/system_architecture/).
+1. Project managers use the **Manager Dashboard** to upload project information (e.g. area of interest, objects to look for) to the backend, which syncs it to the Firebase Realtime Database.
+2. In the final phase of project creation, a tutorial must be attached before the project can be published — either an existing shared tutorial or one specialised for the project.
+3. Once the project is published from the **Manager Dashboard**, the backend creates the relevant groups and tasks and syncs them to Firebase.
+4. Users of the MapSwipe app contribute to projects and submit their results through the app; these are stored in both the Firebase Realtime Database. **Firebase rules** ensure that app users can only change pre-defined parts of the Firebase Realtime Database.
+5. As new results arrive, **Firebase functions** and the **backend** generate real-time statistics — updating group progress and computing project and user statistics.
+6. Results are synchronised between the **backend** and **Firebase** on a defined schedule (e.g. every 10 minutes). The backend database holds all MapSwipe results for long-term storage; once results are synced and then deletes them from the Firebase Realtime Database.
+7. The **backend** then generates aggregated data and statistics from this stored data and serves them via its GraphQL endpoint.

docs/project_types.md

@@ -6,7 +6,7 @@ permalink: /docs/system_architecture/
 
 # System Architecture
 
-This page describes how the MapSwipe system is put together: the old vs. new architecture, and the individual components that make up the new architecture today. For the typical end-to-end workflow (project request → publish → contribute → export), see [Overview](/docs/overview/).
+This page describes how the MapSwipe system is put together: the old vs. new architecture, and the individual components that make up the new architecture today.
 
 ## Architecture overview
 
@@ -37,14 +37,17 @@ The primary reason for keeping Firebase as the primary database was auto-scaling
 
 The major difference in the new architecture is that **Postgres is the primary database**. Only the MapSwipe mobile and web apps interface with Firebase directly. The system stays scalable and reliable while significantly reducing the usage of the Firebase Realtime Database. See the [Components](#components) section below for an inventory of the pieces.
 
+> [!NOTE]
+> **Firebase Endpoints** shown in the new architecture diagram is planned for a future iteration and has not yet been implemented. Today, the mobile and web apps still read from and write to the Firebase Realtime Database directly.
+
 ## Components
 
 ### Public Website
 
 - **Source:** [`mapswipe/website`](https://github.com/mapswipe/website)
 - **Deployed at:** <https://mapswipe.org/>
 
-The public marketing and information site for MapSwipe — what MapSwipe is, recent projects, the organisations behind it, and links to the apps and dashboards.
+The public-facing website for MapSwipe — an introduction to the project, recent mapping work, the organisations behind it, and links to the apps and dashboards.
 
 ### Mobile App
 
@@ -75,16 +78,14 @@ A React-based static site showcasing aggregated MapSwipe contribution stats, plu
 
 The central **Django server** backed by Postgres. A single service is responsible for:
 
-- The **GraphQL API** consumed by the [Manager Dashboard](#manager-dashboard) and the [Community Dashboard](#community-dashboard). (REST endpoints from earlier iterations are no longer used.)
+- The **GraphQL API** consumed by the [Manager Dashboard](#manager-dashboard) and the [Community Dashboard](#community-dashboard).
 - **Data synchronisation** between Postgres and Firebase Realtime Database — including the background workers that transfer in-flight results out of Firebase and into Postgres for long-term storage.
 - The **data-export generation** that produces the files documented under [About the Data](/docs/about_data/).
 
-The state machines that drive the [project lifecycle](/docs/for_project_managers/projects/#status-flow) and the [tutorial lifecycle](/docs/for_project_managers/tutorials/#status-flow) are also defined here (in `apps/project/serializers.py` and `apps/tutorial/serializers.py`).
-
 ### Firebase Cloud Functions
 
 - **Source:** [`mapswipe/mapswipe-firebase`](https://github.com/mapswipe/mapswipe-firebase)
 
-Cloud Functions that react to Firebase Realtime Database events — incrementing per-user contribution counters when results arrive, propagating user-group membership changes, queuing PSQL-sync flags so the backend knows what changed, and serving the OSM OAuth handshake.
+Cloud Functions that react to Firebase Realtime Database events — incrementing per-user contribution counters when results arrive, propagating user-group membership changes, queuing PSQL-sync flags so the backend knows what changed, and serving the OSM OAuth login.
 
-The functions co-exist with the runtime **Firebase Realtime Database**, which holds active project / group / task data and in-flight result submissions until the backend workers transfer them to Postgres.
+The functions co-exist with the runtime **Firebase Realtime Database**, which holds active project / group / task data and in-flight result submissions until the backend workers transfer them to Postgres database.

docs/system_architecture.md

@@ -6,9 +6,6 @@ permalink: /docs/use_cases/
 
 # Use Cases
 
-> [!NOTE]
-> This page is based on the first version of MapSwipe and contains some outdated information. It's still a useful starting point for thinking about whether a project is a good fit for MapSwipe.
-
 ## How to identify "good" mapping tasks for MapSwipe
 
 MapSwipe projects can cover large areas in comparison to other mapping approaches, e.g. using the HOT Tasking Manager. Nevertheless, the level of detail of the resulting information you can expect from the resulting data will be lower than using the data from OpenStreetMap.

docs/use_cases.md

@@ -9,7 +9,8 @@ permalink: /examples/
 
 Worked examples and reference scripts for interacting with MapSwipe.
 
-> **Note:** Ongoing updates to MapSwipe may render these examples out-of-date. They are intended as a starting point and assume read-only access where applicable.
+> [!NOTE]
+> Ongoing updates to MapSwipe may render these examples out-of-date. They are intended as a starting point and assume read-only access where applicable.
 
 - [Fetch Project Data](/examples/fetch-project-data/) — read-only download of a project's public data exports.
 - [Fetch Global Data](/examples/fetch-global-data/) — read-only download of the four MapSwipe-wide global exports.

examples/index.md

@@ -14,12 +14,13 @@ validating map data, MapSwipers help improve map data across the world.
 
 ## Where to start
 
-- **[Overview](/docs/overview/)** — how MapSwipe is put together, old vs. new architecture, and how the pieces fit together.
-- **[About the Data](/docs/about_data/)** — the global and project-specific exports MapSwipe makes available, and what every column means.
+- **[Overview](/docs/overview/)** — the typical MapSwipe workflow, from project request through publish, contribute, and export.
+- **[System Architecture](/docs/system_architecture/)** — how MapSwipe is put together: system architecture and the components that make up the system today.
 - **[Project Types](/project_types/)** — Find Features, Validate Footprints, Compare Dates, Assess Images, Check Completeness, and View Streets.
-- **[For Project Managers](/docs/for_project_managers/)** — how to become a project manager, set up new projects, manage tutorials, organisations, and teams.
-- **[Examples](/examples/)** — reference scripts and code snippets for interacting with the MapSwipe backend.
-- **[Local Development](/docs/docs_local_development/)** — how to run this docs site locally.
+- **[About the Data](/docs/about_data/)** — the global and project-specific exports MapSwipe makes available, and what every column means.
+- **[For Project Managers](/docs/for_project_managers/)** — how to become a project manager, set up new projects, and manage tutorials, organisations, and teams.
+- **[Examples and Scripts](/examples/)** — reference scripts and code snippets for interacting with the MapSwipe backend.
+- **[Use Cases](/docs/use_cases/)** — when MapSwipe is a good fit, and the kinds of mapping problems it can help with.
 
 ## Useful links