Documentation strategy and structure

This document is a high-level guide for maintainers and contributors. It defines the structure, audience, and style for the MATS application documentation. It is directly inspired and influenced by Jupyter Book’s own “contributing” documentation.

Documentation Structure¶

Our documentation is organized into top-level sections based on audience. The site/ directory contains folders that correspond directly to these top-level URL paths:

• Landing Page (index.md)

  • Audience: Newcomers and all users.

  • Content: The file site/index.md becomes the effective-chainsaw-mwovpgw.pages.github.io/ landing page. It should demonstrate the core value proposition of the MATS tool, and give all the information needed to orient a new user and know where to look for more information. It should be easy to read, simple, and visually attractive.

• Diataxis Framework Categories (e.g., how-to-guides/, explanation/, etc...)

  • Audience: Users of MATS.

  • Content: These are the main documentation for the product. They live in their own top-level folders. For example, all content related to How-to Guides lives in the how-to-guides/ folder.

• Landing Pages (e.g., how-to-guides.md, explanation.md)

  • Audience: Users exploring a specific Diataxis category.

  • Content: Each major Diataxis category should have a landing page that provides the same function as the main landing page, but focused on the contents of that category. The landing page should be simple, visually attractive, and guide users to content organized by topic. These files become the /how-to-guide, /explanation URLs and should be low-maintenance—linking to existing content rather than duplicating it.

• Contributor Docs (contribute/)

  • Audience: Contributors to the MATS documentation.

  • Content: How to navigate the project’s repositories, know where to make a contribution, project-wide contributing guidelines and styles, and how to set up the project for development.

Topic Organization¶

Our documentation should be categorized by the Diataxis framework.

• tutorials: Goal-oriented guides to lead a user through a complete process (e.g., “Verify your first retro”). These are usually standalone guides.

• how-to: Short, focused guides to answer a specific question (e.g., “How do I do a Retrospective Grid to Observation METAR verification?”).

• explanation: Explanations of key concepts and high-level discussions (e.g., “How we calculate Skill Scores”).

• reference: Technical descriptions and factual information (e.g., “Rocoto Cheat Sheet”).

Pages are organized in a flat hierarchy within each framework folder, try not to nest them inside sub-folders unless really needed.

Example structure¶

Good structure following this guide:

site/
├── index.md                              # Main landing page
├── how-to-guides.md                      # Diataxis Framework landing page
├── how-to-guides/
│   ├── retro-grid2obs-restoring-data.md  # Guide for retro grid2obs verification
│   ├── retro-metplus-tc.md               # Guide for retro metplus tropical cyclone verification
│   └── rt-grid2grid-amdar.md             # Guide for realtime grid2grid amdar verification
└── explanation/
    ├── guiding-principles.md             # Explanation of guiding verification principles
    └── std-error.md                      # Discussion of how error is calculated in MATS

Avoid:

• how-to-guides/index.md (MyST limitation, use how-to-guides.md instead)

• Mixing content types in one page (tutorial + reference together)

• Deep nesting (prefer flat structure within topic areas)

• Long filenames (prefer short names where possible)

How can I tell what type of content I’m adding?¶

Use the Diataxis compass to decide what type of content you’re adding. Here’s the key table they recommend:

Development Workflow¶

Building the documentation¶

The MATS docs repository includes a pyproject.toml to cover the project’s dependencies. Jupyter Book itself has commands for building and previewing the documentation that can be run through uv:

Build static HTML:

uv run jupyter book build --html

Start live development server:

uv run jupyter book start

The live server will automatically rebuild pages as you edit them, making it easy to preview your changes.

Repository structure¶

• site/ - All documentation source files

• pyproject.toml - Project dependencies

See the project README.md for a complete overview.

Style¶

• Use active and short language instead of passive language (e.g., Get started rather than Getting started)

• Be direct and to-the-point. Avoid overly wordy sections.

• Make documentation scannable. Provide high-information headers and titles.

• Cross-reference heavily. Rather than re-writing content, link back to a section as a source of truth.

• To reference scientific papers and articles, use doi.org links so that the MyST engine can automatically provide a references section.

• Abbreviations should be definied in the project-level frontmatter fields, which are in the site/abbreviations.yml file (extended by myst.yml).

• Pages with long titles should have page-level short_title frontmatter defined.