Documentation Conventions
=========================

The documentation site is meant to function as both a user manual and a public
API reference. That only works if documentation changes follow consistent
conventions.

Content Rules
-------------

- Document public surfaces by user intent first, then by module structure.
- Keep a clear separation between ``Stable``, ``Advanced``, and
  ``Experimental / partial`` capabilities.
- Explain the thermodynamic decision question before explaining the API call.
- Prefer one practical workflow example per page over long enumerations of
  loosely related features.
- When a new public method or CLI command is added, update both the curated
  narrative page and the exhaustive reference appendix.

Page Categories
---------------

``Overview``
   What the package does, when to use it, and how to choose a workflow.

``Fundamentals``
   Thermodynamic and architectural grounding in package terms.

``Guides``
   Task-oriented walkthroughs that answer one practical question.

``API``
   Curated public reference first, exhaustive module appendix second.

``Examples``
   Packaged notebooks, sample cases, and decision-workflow mapping.

Writing Style
-------------

- Use the same terminology as the code and the result tables.
- Write core OpenPinch concepts in spaced title case in prose, for example
  ``Total Site``, ``Total Process``, ``Heat Pump``, ``Problem Table``, and
  ``Composite Curve``. Reserve hyphenated forms for literal file names, page
  paths, CLI commands, graph IDs, and other API values.
- Avoid marketing language and generic claims about optimization.
- State package boundaries explicitly when a feature is partial or
  intentionally lower level.
- Link examples, guides, and API pages together so readers can move from
  concept to execution without guessing.

Docs Maintenance Expectations
-----------------------------

- Public API changes should ship with docs updates in the same change.
- New packaged notebooks or sample cases should be added to the examples pages.
- If a surface is intentionally experimental, keep it out of the stable guides
  and mark it clearly in the support matrix.