Reorganizing documentation

[dlebauer]

I am putting notes from our discussion from April 2025 about reorganizing the PEcAn documentation.

We can discuss and refine here, then prioritize steps and identify specific GH Issues / subtasks.

Minor changes / errors / etc can be reported in the companion thread, #3689

Motivating questions

Content
What can be removed?
What needs to be added?
What needs to be clarified?

Contributing
What would make it easier to contribute to documentation?
What would make it easier for users to read documentation?
Who are target audiences?
Are we happy with current tools and build system?

General Approach

• Developer guide / style etc. Should all be in one place, should be at a higher level
• Main documentation should do a better job of referencing the Pkgdown / Roxygen docs, incorporating vignettes
  • How to vs explanation
    • Royxgen more useful for reference than explanation
    • Main text is about explanation
  • While going through docs, make sure content is in the right place
  • Some packages have vignettes
    • For tutorials cross reference working vignettes; would be nice if these were tested
    • Some stuff that would have been in the book can go in the package documentation and referenced from the book.
• Move away from Legacy UIs
  • Esp. PHP + BETYdb.
  • Also Shiny - lower priority, but take wait and see approach
  • Prioritizing notebook driven and script based workflows.
• Ruthlessly trim. Remove non-essential information. Exclude anything that is out of date or better documented elsewhere.
• Make sure use of headings is consistent
• Combine pages and link from TOC to sections w/in a page rather than separate pages.

Organization

At a high level, the proposed reorganization would follow the following outline

• User Guide - installation & basic workflows
• Advanced Applications - multi-site runs, data constraints, SDA, standalone tools
• Developer’s guide

Adopt Diataxis framework https://diataxis.fr/ to separate tutorials, how-to guides, explanations, reference materials

The current and proposed organization is here: https://docs.google.com/document/d/124cWBUgHFRmzHJuS0QntFSxO6OtgEG4eZRNSf9o6Tv0/edit?tab=t.0

Proposed organization Sections are in bold, subchapters are indented (subchapters are incomplete - additional subchapters added as needed)

Proposed organization
Introduction
Project Overview
- About the PEcAn Book
Code of Conduct
User’s Guide & Tutorials
Install Pecan [How To]
Basic workflow (single site, single model Demo 1) 1
Settings: PEcAn XML [reference]
Input pipelines [reference]
- Meteorological Drivers
- Initial conditions
- Other PEcAn standard formats 2
Parameters & Calibration [mix of all 4]
- Priors and posteriors
- Trait Meta-analysis
- Calibration
Model execution [reference]
- Local, remote, cloud, API
- Supported Models 3
Validation & Visualization
Troubleshooting, FAQ
Advanced Applications
Sensitivity and uncertainty analysis
Multi-site runs
- code-based multi settings
- gridded vs. irregular, vector
- site selection
Downscaling
Data Constraint pipelines on model outputs 4
State Data Assimilation
Stand Alone Tools (allom, RTM, photosynthesis, etc)
BETY database (use, admin, sync)
Developer’s Guide
Your first pull request
Coding Style
Documentation: Roxygen, book, logs, etc
Testing with the testhat package
Continuous Integration
Adding to PEcAn: new models, inputs, constraints, etc.
Docker 5
Information for GSOC students
Appendices
Web interfaces (php, ruby)
Administrative details

Footnotes

1. Basic workflow would contain both an overview and tutorial. Focus on notebook and script-based interfaces - omit web UI; references to other sections. Details in following sections ↩

2. soil physics, phenology, events, etc. ↩

3. need to update and link to READMEs in model packages ↩

4. Mirrors Input pipelines but focuses on the pipelines used for acquiring the data used in the SDA (and calibration?) and the new standards that have emerged there. Could pull up to after the Inputs, which would make sense for the Calibration and Validation sections, but then would be before multisite. Could also pull up multisite ↩

5. Most Docker info is currently in Dev-Intro ↩