GEOS-ESM · ftgoktas · Jul 23, 2026 · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,60 +1,80 @@
-- Getting started
-
-  - [Installing swell](installing_swell.md)
-  - [Configuring `cylc`](configuring_cylc.md)
-  - [Creating an experiment](creating_an_experiment.md)
-  - [Launching an experiment](launching_an_experiment.md)
-  - [Monitoring an experiment](monitoring_an_experiment.md)
-  - [Manually running tasks](manually_running_tasks.md)
-
-- Platform specific instructions
-
-  - [Platforms](platforms/platforms.md)
-  - **Discover**
-    - [Installing Swell on SLES15](platforms/discover/installing_swell_discover_sles15.md)
-    - [Installing Swell using `uv` and `venv`](platforms/discover/installing_swell_uv_venv.md)
-    - [Installing Swell with `uv` without internet access](platforms/discover/installing_swell_uv_offline.md)
-    - [Configuring `cylc`](platforms/discover/configuring_cylc_discover.md)
-
-- Practical Examples
-
-  - [Description](examples/description.md)
-  - **SOCA**
-    -  [3DVAR_marine](examples/soca/3dvar_marine.md)
-    -  [3DVAR_marine_cycle_tier2]((examples/soca/3dfgat_marine_cycle_tier2.md))
-    -  [3DFGAT_marine_cycle]((examples/soca/3dfgat_marine_cycle.md))
-  - **R2D2 - Storing Data**
-       - [Understanding R2D2](examples/r2d2_intro.md)
-       - [Storing Observations to R2D2](examples/r2d2/r2d2_ingest.md)
-
-- Configuration files in swell
-
-  - [Observation configuration](configs/observation_configuration.md)
-  - [R2D2 v3 credentials](configs/r2d2_v3_credentials.md)
-  - [SLURM configuration](configs/slurm_configuration.md)
-  - Model configuration:
-    - [Storing Observations to R2D2](examples/r2d2/r2d2_ingest.md)
-  - **SWELL Generic Suites**
-    - [Comparing two SWELL experiment outputs](examples/comparison_workflows.md)
-
-- Configuration files in swell
-
-  - Model configurations:
-    - [CICE6](configs/model_configurations/cice6.md)
-    - [MOM6](configs/model_configurations/mom6.md)
-    - [History Outputs](configs/model_configurations/history_outputs.md)
-  - [Observation configuration](configs/observation_configuration.md)
-  - [R2D2 configuration](configs/r2d2_v3_credentials.md)
-  - [SLURM configuration](configs/slurm_configuration.md)
-
-- Code test before pull request
-
-  - [Code Tests](code_tests/code_tests.md)
-  - [Suite Tests](code_tests/suite_tests.md)
-
-- Governance
-
-  - [Requirements](requirements.md)
-
-- [Editing the docs](editing_docs.md)
-- [Useful links](useful_links.md)
+- 1. Getting Started
+
+  - [What Is Swell?](README.md)
+  - [Core Concepts and Terminology](introduction/core_concepts_and_terminology.md) — _No documentation yet_
+  - Prerequisites and Supported Platforms
+    - [Prerequisites](introduction/prerequisites.md) — _No documentation yet_
+    - [Supported Platforms](installation_and_setup/platforms/README.md)
+    - [Project Requirements and Goals](introduction/requirements.md)
+  - Installation and Setup
+    - [Installing Swell](installation_and_setup/installing_swell.md)
+    - [Configuring Cylc](installation_and_setup/configuring_cylc.md)
+    - Discover
+      - [Installing Swell on SLES15](installation_and_setup/platforms/discover/installing_swell_discover_sles15.md)
+      - [Installing Swell with `uv` and `venv`](installation_and_setup/platforms/discover/installing_swell_uv_venv.md)
+      - [Installing Swell Without Internet Access](installation_and_setup/platforms/discover/installing_swell_uv_offline.md)
+      - [Installing Swell in an Interactive C Shell](installation_and_setup/platforms/discover/installing_swell_csh_interactive.md)
+      - [Configuring Cylc on Discover](installation_and_setup/platforms/discover/configuring_cylc_discover.md)
+  - [QuickStart](introduction/quickstart.md) — _No documentation yet_
+
+- 2. Running Experiments
+
+  - [Choosing a Workflow](running_an_experiment/choosing_a_workflow.md) — _No documentation yet_
+  - Understanding Configuration
+    - [Current Configuration and Experiment Overview](practical_examples/README.md)
+    - [SLURM Configuration](configuration_reference/slurm_configuration.md)
+  - [Creating an Experiment](running_an_experiment/creating_an_experiment.md)
+  - [Modifying an Experiment with Overrides](practical_examples/README.md?id=using-defaults-with-overrides)
+  - [Generated Directory Layout](practical_examples/README.md?id=experiment-directory)
+  - [Launching an Experiment](running_an_experiment/launching_an_experiment.md)
+  - Monitoring, Restarting, and Stopping
+    - [Monitoring an Experiment](running_an_experiment/monitoring_an_experiment.md)
+    - [Stopping Jobs](running_an_experiment/launching_an_experiment.md?id=stopping-jobs)
+  - Logs and Output Products
+    - [Finding Task Logs](running_an_experiment/monitoring_an_experiment.md?id=when-a-task-fails)
+  - [Manually Running Tasks](running_an_experiment/manually_running_tasks.md)
+  - [Troubleshooting](running_an_experiment/troubleshooting.md) — _No documentation yet_
+
+- 3. Workflow Guides
+
+  - Ocean and Sea-Ice DA
+    - [3DVAR Marine](practical_examples/soca/3dvar_marine.md)
+    - [3DVAR Marine Cycle Tier 2](practical_examples/soca/3dvar_marine_cycle_tier2.md)
+    - [3DFGAT Marine Cycle](practical_examples/soca/3dfgat_marine_cycle.md)
+  - [Atmospheric (Weather) DA](practical_examples/atmosphere/README.md) — _No documentation yet_
+  - [GEOS-CF (Composition) DA](practical_examples/geos_cf/README.md) — _No documentation yet_
+  - Background Ingestion, Observation Ingestion, and Conversion
+    - [Storing Observations and Backgrounds in R2D2](practical_examples/r2d2/r2d2_ingest.md)
+  - Comparison and Evaluation
+    - [Comparing Experiment Outputs](practical_examples/generic_suites/comparison_workflows.md)
+
+- 4. Data and R2D2
+
+  - [R2D2 Concepts](introduction/r2d2_overview.md)
+  - [Credentials](configuration_reference/r2d2_v3_credentials.md)
+  - [Servers and Datastores](installation_and_setup/configuring_aws_server.md)
+  - [How Experiments Store and Retrieve Data](introduction/r2d2_overview.md?id=how-swell-uses-r2d2)
+
+- 5. Extending Swell
+
+  - [Adding a Task](extending_swell/adding_a_suite.md?id=writing-tasks)
+  - [Adding a Suite/Workflow](extending_swell/adding_a_suite.md)
+  - [Adding Model Interfaces](extending_swell/adding_model_interfaces.md) — _No documentation yet_
+  - [Adding Observations and Converters](extending_swell/adding_observations_and_converters.md) — _No documentation yet_
+  - [Adding Platform Support](extending_swell/adding_platform_support.md) — _No documentation yet_
+
+- 6. Testing and Contributing
+
+  - [Development Setup](testing_and_contributing/development_setup.md) — _No documentation yet_
+  - [Code Tests](testing_and_contributing/code_tests.md)
+  - [Tier 1 and Tier 2 Suite Tests](testing_and_contributing/suite_tests.md)
+  - [Documentation](testing_and_contributing/editing_docs.md)
+  - [Contribution Guidelines](testing_and_contributing/contribution_guidelines.md) — _No documentation yet_
+
+- 7. Additional Resources
+
+  - [Useful Links](additional_resources/useful_links.md)
+  - Physical Model Settings
+    - [CICE6](configuration_reference/model_configurations/cice6.md)
+    - [MOM6](configuration_reference/model_configurations/mom6.md)
+    - [History Outputs](configuration_reference/model_configurations/history_outputs.md)
diff --git a/docs/useful_links.md → docs/additional_resources/useful_links.md b/docs/useful_links.md → docs/additional_resources/useful_links.md
diff --git a/docs/configs/model_configurations/cice6.md → ...n_reference/model_configurations/cice6.md b/docs/configs/model_configurations/cice6.md → ...n_reference/model_configurations/cice6.md
diff --git a/...s/model_configurations/history_outputs.md → ...e/model_configurations/history_outputs.md b/...s/model_configurations/history_outputs.md → ...e/model_configurations/history_outputs.md
diff --git a/docs/configs/model_configurations/mom6.md → ...on_reference/model_configurations/mom6.md b/docs/configs/model_configurations/mom6.md → ...on_reference/model_configurations/mom6.md
diff --git a/docs/configs/observation_configuration.md → ...on_reference/observation_configuration.md b/docs/configs/observation_configuration.md → ...on_reference/observation_configuration.md
diff --git a/docs/configs/r2d2_v3_credentials.md → ...guration_reference/r2d2_v3_credentials.md b/docs/configs/r2d2_v3_credentials.md → ...guration_reference/r2d2_v3_credentials.md
diff --git a/docs/configs/slurm_configuration.md → ...guration_reference/slurm_configuration.md b/docs/configs/slurm_configuration.md → ...guration_reference/slurm_configuration.md
diff --git a/docs/documentation_outline.md b/docs/documentation_outline.md
@@ -0,0 +1,138 @@
+# Swell Documentation Outline
+
+This outline is the planning and assignment checklist for the documentation code sprint. It follows
+the organization in `_sidebar.md`.
+
+Status definitions:
+
+- **Existing**: A dedicated page or substantial documentation already exists.
+- **Partial**: Related material exists, but it does not fully cover the proposed section.
+- **Missing**: No corresponding documentation currently exists.
+
+## 1. Getting Started
+
+Owner: __________
+
+- [ ] **1.a. What Is Swell?** — **Existing**
+  - Current documentation: [What Is Swell?](README.md)
+- [ ] **1.b. [Core Concepts and Terminology](introduction/core_concepts_and_terminology.md)** — **Missing**
+- [ ] **1.c. Prerequisites and Supported Platforms** — **Partial**
+  - [Prerequisites](introduction/prerequisites.md): **Missing**
+  - Current documentation: [Supported Platforms](installation_and_setup/platforms/README.md)
+  - Related documentation: [Project Requirements and Goals](introduction/requirements.md)
+- [ ] **1.d. Installation and Setup** — **Existing**
+  - [Installing Swell](installation_and_setup/installing_swell.md)
+  - [Configuring Cylc](installation_and_setup/configuring_cylc.md)
+  - Discover
+    - [Installing Swell on SLES15](installation_and_setup/platforms/discover/installing_swell_discover_sles15.md)
+    - [Installing Swell with `uv` and `venv`](installation_and_setup/platforms/discover/installing_swell_uv_venv.md)
+    - [Installing Swell Without Internet Access](installation_and_setup/platforms/discover/installing_swell_uv_offline.md)
+    - [Installing Swell in an Interactive C Shell](installation_and_setup/platforms/discover/installing_swell_csh_interactive.md)
+    - [Configuring Cylc on Discover](installation_and_setup/platforms/discover/configuring_cylc_discover.md)
+- [ ] **1.e. [QuickStart](introduction/quickstart.md)** — **Missing**
+  - Scope: Summarize the steps required to create, launch, monitor, and verify an experiment.
+
+## 2. Running Experiments
+
+Owner: __________
+
+- [ ] **2.a. [Choosing a Workflow](running_an_experiment/choosing_a_workflow.md)** — **Missing**
+  - Scope: Help users choose among HofX, 3DVAR, ensemble DA, ingestion, comparison, cycling and
+    non-cycling workflows, and supported model components. A selection table or workflow catalog
+    would be useful.
+- [ ] **2.b. Understanding Configuration** — **Partial**
+  - Scope: Explain how `experiment.yaml` is assembled and all the ways a user can configure an
+    experiment.
+  - Current related documentation:
+    [Configuration and Experiment Overview](practical_examples/README.md)
+  - External starting point:
+    [How to configure a Swell experiment](https://github.com/mer-a-o/howtojedi/blob/4d076aed6f160f0ab4d99cfad1d8acdcaaafdd4e/jedi_trainings/swell/2.configure.md)
+  - Current documentation: [SLURM Configuration](configuration_reference/slurm_configuration.md)
+- [ ] **2.c. Creating an Experiment** — **Existing**
+  - Current documentation: [Creating an Experiment](running_an_experiment/creating_an_experiment.md)
+- [ ] **2.d. Modifying an Experiment** — **Partial**
+  - Current related documentation:
+    [Modifying an Experiment with Overrides](practical_examples/README.md?id=using-defaults-with-overrides)
+- [ ] **2.e. Generated Directory Layout** — **Existing**
+  - Current documentation:
+    [Experiment Directory](practical_examples/README.md?id=experiment-directory)
+- [ ] **2.f. Launching an Experiment** — **Existing**
+  - Current documentation: [Launching an Experiment](running_an_experiment/launching_an_experiment.md)
+- [ ] **2.g. Monitoring, Restarting, and Stopping** — **Partial**
+  - [Monitoring an Experiment](running_an_experiment/monitoring_an_experiment.md)
+  - [Stopping Jobs](running_an_experiment/launching_an_experiment.md?id=stopping-jobs)
+  - Restarting and recovery guidance: **Missing**
+- [ ] **2.h. Logs and Output Products** — **Partial**
+  - Current related documentation:
+    [Finding Task Logs](running_an_experiment/monitoring_an_experiment.md?id=when-a-task-fails)
+  - General output-product guidance: **Missing**
+- [ ] **2.i. Manually Running Tasks** — **Existing**
+  - Current documentation:
+    [Manually Running Tasks](running_an_experiment/manually_running_tasks.md)
+- [ ] **2.j. [Troubleshooting](running_an_experiment/troubleshooting.md)** — **Missing**
+
+## 3. Workflow Guides
+
+- [ ] **3.a. Ocean and Sea-Ice DA** — **Existing** — Owner: __________
+  - [3DVAR Marine](practical_examples/soca/3dvar_marine.md)
+  - [3DVAR Marine Cycle Tier 2](practical_examples/soca/3dvar_marine_cycle_tier2.md)
+  - [3DFGAT Marine Cycle](practical_examples/soca/3dfgat_marine_cycle.md)
+- [ ] **3.b. [Atmospheric (Weather) DA](practical_examples/atmosphere/README.md)** — **Missing** — Owner: __________
+- [ ] **3.c. [GEOS-CF (Composition) DA](practical_examples/geos_cf/README.md)** — **Missing** — Owner: __________
+- [ ] **3.d. Background Ingestion, Observation Ingestion, and Conversion** — **Existing** — Owner: __________
+  - Current documentation:
+    [Storing Observations and Backgrounds in R2D2](practical_examples/r2d2/r2d2_ingest.md)
+- [ ] **3.e. Comparison and Evaluation** — **Existing** — Owner: __________
+  - Current documentation:
+    [Comparing Experiment Outputs](practical_examples/generic_suites/comparison_workflows.md)
+
+## 4. Data and R2D2
+
+Owner: __________
+
+- [ ] **4.a. R2D2 Concepts** — **Existing**
+  - Current documentation: [R2D2 Concepts](introduction/r2d2_overview.md)
+- [ ] **4.b. Credentials** — **Existing**
+  - Current documentation: [R2D2 Credentials](configuration_reference/r2d2_v3_credentials.md)
+- [ ] **4.c. Servers and Datastores** — **Existing**
+  - Current documentation:
+    [Configuring R2D2 Servers and Datastores](installation_and_setup/configuring_aws_server.md)
+- [ ] **4.d. How Experiments Store and Retrieve Data** — **Existing**
+  - Current documentation:
+    [How Swell Uses R2D2](introduction/r2d2_overview.md?id=how-swell-uses-r2d2)
+
+## 5. Extending Swell
+
+Owner: __________
+
+- [ ] **5.a. Adding a Task** — **Partial**
+  - Current documentation: [Writing Tasks](extending_swell/adding_a_suite.md?id=writing-tasks)
+- [ ] **5.b. Adding a Suite/Workflow** — **Existing**
+  - Current documentation: [Adding a Suite](extending_swell/adding_a_suite.md)
+- [ ] **5.c. [Adding Model Interfaces](extending_swell/adding_model_interfaces.md)** — **Missing**
+- [ ] **5.d. [Adding Observations and Converters](extending_swell/adding_observations_and_converters.md)** — **Missing**
+- [ ] **5.e. [Adding Platform Support](extending_swell/adding_platform_support.md)** — **Missing**
+
+## 6. Testing and Contributing
+
+Owner: __________
+
+- [ ] **6.a. [Development Setup](testing_and_contributing/development_setup.md)** — **Missing**
+- [ ] **6.b. Code Tests** — **Existing**
+  - Current documentation: [Code Tests](testing_and_contributing/code_tests.md)
+- [ ] **6.c. Tier 1 and Tier 2 Suite Tests** — **Existing**
+  - Current documentation: [Suite Tests](testing_and_contributing/suite_tests.md)
+- [ ] **6.d. Documentation** — **Existing**
+  - Current documentation: [Editing the Documentation](testing_and_contributing/editing_docs.md)
+- [ ] **6.e. [Contribution Guidelines](testing_and_contributing/contribution_guidelines.md)** — **Missing**
+
+## 7. Additional Resources
+
+Owner: __________
+
+- [ ] **7.a. Useful Links and Additional Resources** — **Existing**
+  - Current documentation: [Useful Links](additional_resources/useful_links.md)
+- [ ] **7.b. Physical Model Settings** — **Existing**
+  - [CICE6](configuration_reference/model_configurations/cice6.md)
+  - [MOM6](configuration_reference/model_configurations/mom6.md)
+  - [History Outputs](configuration_reference/model_configurations/history_outputs.md)
diff --git a/docs/adding_a_suite.md → docs/extending_swell/adding_a_suite.md b/docs/adding_a_suite.md → docs/extending_swell/adding_a_suite.md
diff --git a/docs/extending_swell/adding_model_interfaces.md b/docs/extending_swell/adding_model_interfaces.md
@@ -0,0 +1,9 @@
+# Adding a Model Interface
+
+> Documentation sprint placeholder. This topic is currently marked **Missing**.
+
+## Planned coverage
+
+- Describe the model-interface directory structure and required files.
+- Add model, observation, question, and template configuration.
+- Test a new model interface.
diff --git a/docs/extending_swell/adding_observations_and_converters.md b/docs/extending_swell/adding_observations_and_converters.md
@@ -0,0 +1,9 @@
+# Adding Observations and Converters
+
+> Documentation sprint placeholder. This topic is currently marked **Missing**.
+
+## Planned coverage
+
+- Add observation configuration and observing-system records.
+- Configure download, conversion, ingestion, and JEDI rendering.
+- Test new observation types and converters.
diff --git a/docs/extending_swell/adding_platform_support.md b/docs/extending_swell/adding_platform_support.md
@@ -0,0 +1,9 @@
+# Adding Platform Support
+
+> Documentation sprint placeholder. This topic is currently marked **Missing**.
+
+## Planned coverage
+
+- Add platform defaults, modules, properties, and scheduler configuration.
+- Explain platform detection and selection.
+- Test experiment creation and execution on a new platform.
diff --git a/docs/configuring_aws_server.md → ...ation_and_setup/configuring_aws_server.md b/docs/configuring_aws_server.md → ...ation_and_setup/configuring_aws_server.md
diff --git a/docs/configuring_cylc.md → ...nstallation_and_setup/configuring_cylc.md b/docs/configuring_cylc.md → ...nstallation_and_setup/configuring_cylc.md
diff --git a/docs/installing_swell.md → ...nstallation_and_setup/installing_swell.md b/docs/installing_swell.md → ...nstallation_and_setup/installing_swell.md
@@ -1,6 +1,6 @@
 # Installing swell
 
-Before you start reading this you may wish to check the platforms page to see if there are [platform](platforms/platforms.md) specific instructions that might be helpful.
+Before you start reading this you may wish to check the platforms page to see if there are [platform](platforms/README.md) specific instructions that might be helpful.
 
 Before installing `swell` you need to think about the dependencies. There are a number of dependencies of `swell`, such as `netCDF` that are likely also dependencies of the applications that `swell` will drive. For maximum safety these dependencies should be satisfied equivalently. For example, if you install `swell` using pip but do not have `netCDF` in the path then pip will take care of this install but will pick its own version. In order to access `swell` this version of `netCDF` installed by pip will have to be in the path. But if `swell` goes on to run an executable that was installed pointing to a different version of `netCDF` problems (that could be hard to diagnose) will likely follow. For the JEDI software system `spack` is utilized to ensure common dependencies and backends. Once development stabilizes we will add `swell` to the same `spack` system. In any case the following directions can be used to install `swell` but some thought to the dependencies is needed so it can be used effectively.
 
@@ -34,4 +34,4 @@ To make the software usable ensure `/path/to/install/swell/bin` is in the `$PATH
 Swell makes use of additional packages which are located in shared directories on Discover, such as under `/discover/nobackup/projects/gmao`. When installed correctly, many of these libraries should be visible in the `$PYTHONPATH`.
 
 
-Configure `~/.swell/r2d2_credentials.yaml` as described in [R2D2 v3 credentials](configs/r2d2_v3_credentials.md).
+Configure `~/.swell/r2d2_credentials.yaml` as described in [R2D2 v3 credentials](../configuration_reference/r2d2_v3_credentials.md).
diff --git a/docs/installation_and_setup/platforms/README.md b/docs/installation_and_setup/platforms/README.md
@@ -0,0 +1,10 @@
+# Platforms
+
+
+This section outlines platform specific instructions for installing and configuring SWELL.
+
+- Discover:
+  - [Cylc Instructions](discover/configuring_cylc_discover.md)
+  - [SWELL Installation with pip & modules](discover/installing_swell_discover_sles15.md)
+  - [SWELL Installation using `uv`](discover/installing_swell_uv_venv.md)
+  - [SWELL Installation with `uv` without internet access](discover/installing_swell_uv_offline.md)
diff --git a/...rms/discover/configuring_cylc_discover.md → ...rms/discover/configuring_cylc_discover.md b/...rms/discover/configuring_cylc_discover.md → ...rms/discover/configuring_cylc_discover.md
diff --git a/...cover/installing_swell_csh_interactive.md → ...cover/installing_swell_csh_interactive.md b/...cover/installing_swell_csh_interactive.md → ...cover/installing_swell_csh_interactive.md
@@ -47,4 +47,4 @@ git clone https://github.com/GEOS-ESM/swell.git swell-develop
 1) Switch to your folder where SWELL is installed: `cd $NOBACKUP/swell-project/mybranch`.
 2) Load all the modules that SWELL needs: `mod_swell`
 3) Activate the virtual environment: `source .venv/bin/activate.csh`. You may also use the full path: `source $NOBACKUP/swell-project/mybranch/.venv/bin/activate.csh`. You may consider adding this command to your `mod_swell` alias for future use.
-4) SWELL is ready! See [examples here](../../examples/description.md) on how to run SWELL.
+4) SWELL is ready! See [examples here](../../../practical_examples/README.md) on how to run SWELL.
diff --git a/...cover/installing_swell_discover_sles15.md → ...cover/installing_swell_discover_sles15.md b/...cover/installing_swell_discover_sles15.md → ...cover/installing_swell_discover_sles15.md
@@ -48,4 +48,4 @@ After the install is completed you should have directories `src`, `modulefiles`
 ```
 **Important:** After logging out of Discover and then logging back in, users should source the JEDI module files again by repeating step 2 above before using `module load swell/<local_name>`.
 
-SWELL is ready to use! See [examples here](../../examples/description.md) on how to run SWELL.
+SWELL is ready to use! See [examples here](../../../practical_examples/README.md) on how to run SWELL.