Reorganize the Omega documentation around the questions readers bring

[xylar]

Reorganize the Omega documentation from one page per source module into a User Guide, Developer Guide and Technical Guide, each answering one kind of question, with the design documents kept as a frozen archive. This draft starts with the design document so the structure and principles can be reviewed before pages move; the reorganization itself will follow on this branch.

The shape is a hybrid: the E3SM User/Developer/Technical Guide triad on the outside, a MOM6-style science spine inside the Technical Guide. The User Guide is organized by task (build, run, configure, I/O, model options), the Developer Guide by what a developer is trying to do (getting started, contributing, framework, model, how-to recipes), and the math moves out of the Developer Guide into the Technical Guide. Section 3 of the design surveys MOM6, MITgcm, NEMO, ROMS, Oceananigans and the E3SM component docs and says what we take from each; section 5 lists the principles a reviewer should hold future doc changes to.

For reviewers to weigh in on:

• The eleven principles in section 5, especially "one home per fact" and "design documents are frozen".
• Generating the configuration reference from a sidecar configs/ConfigDescriptions.yml (section 6.7) rather than from descriptions in the C++ Config::get calls, which stays open as a discussion item.
• Publishing one directory per version on gh-pages, Polaris-style, in this PR (section 6.9).
• Breaking old page URLs without redirects (section 6.6).

This PR restructures and writes the connective pages only. A real user quick start, running-in-E3SM pages, migrating the governing equations into the Technical Guide, the remaining how-to recipes and tutorials will be placeholders with tracking issues (section 7).

Checklist

• Documentation:
  • Design document has been generated and added to the docs
  • User's Guide has been updated
  • Developer's Guide has been updated
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally

---

Posted by Claude Code on @xylar's behalf. The analysis and wording above are AI-authored; please check them accordingly.

🤖 Generated with Claude Code

[xylar]

@sbrus89, could you give this design a look at some point so we can chat about it when we meet next. Not a rush.

[cbegeman]

@xylar I endorse this reorg! I just noticed one thing that was unclear (to me).

[cbegeman]

I'm not clear on how this would be validated and usable

[xylar]

Thanks, that was too terse. I rewrote §6.7 in 74c8d97 to show the descriptions file next to the matching Default.yml section, list what the build checks (every option described, no stale entries, defaults satisfy their own allowed values, doc anchors exist), and say what omega_buildnml can do with the allowed values. Also dropped "sidecar" for "companion file".

---

Posted by Claude Code on @xylar's behalf. The wording above is AI-authored; please check it accordingly.

[vanroekel]

This reorg sounds very logical to me. I'm a little worried about having to carry to Default.yml files, but it seems the best option without touching tons of omega code.

A clarification question on the Description in Default.yml - each parameter would have a description? How long can / should these be and can this be split easily over lines? I'd maybe advocate for a short description in that file then a more robust one in the companion file.

[xylar]

@vanroekel Default.yml doesn't change — no descriptions go in it. All of them live in ConfigDescriptions.yml, so the file you edit to change a default stays exactly as light as it is now. That's most of what you're advocating; the open question is only whether you also want a short description in Default.yml, and my inclination is no, since two descriptions per option is two things to keep in step and the companion file is one git grep away.

On the mechanics: a description is aimed at one or two sentences, there's no limit, and YAML folds over as many lines as you like with no escaping or continuation characters:

HaloWidth:
  description: >-
    Number of halo layers around each subdomain. Must be at least 3
    so that all baroclinic and higher-order tracer advection terms
    can be computed without communication.
  type: int

On carrying two files: the companion never holds a default value, so the two can't disagree about one. What it duplicates is the option names and nesting, and that's exactly what the build check compares — a new option in Default.yml fails CI until it's described, and a renamed or deleted one fails until its description follows. There are 170 options today, so the initial pass is real work, but it's a one-time pass and CI keeps it honest after that.

§6.7 now says all of this outright, since it wasn't clear (0949219).

---

Posted by Claude Code on @xylar's behalf. The wording above is AI-authored; please check it accordingly.

[vanroekel]

Thanks for the explanation and change @xylar