# Documentation Standard

The documentation in this repository describes the **current implementation on
the branch**. As of `2026-07-18`, the active documentation baseline is
**`0.5.0`**.

## Document Types and Organization

### Main Document Types

1. **API reference (`api.md`)**: specifications for public interfaces and
   observable behavior
2. **Tutorial (`tutorial.md`)**: user-oriented examples and selection guidance
3. **Design document (`design.md`)**: capability boundaries, responsibilities,
   and implementation tradeoffs

`README.md` is the current-baseline document. It explains the active release,
package positioning, entry points, and reader guidance. `CHANGELOG.md` owns the
historical release timeline and older release notes.

## Organization Principles

- Organize subsystem documents under the real package or capability boundary.
- Keep `api.md`, `tutorial.md`, and `design.md` distinct in purpose.
- Document only APIs and behavior present in the current branch.
- Keep the Markdown file set aligned across `en_US`, `zh_CN`, and `ja_JP`.
- Keep top-level and second-level section order aligned across languages unless
  a code fact requires a structural difference.
- Treat English as the structural source of truth, then localize the same facts
  naturally into Chinese and Japanese.
- Keep `README.md` focused on the active baseline and move older release
  summaries into `CHANGELOG.md`.

## Writing Requirements

- Do not translate identifiers, type names, trait names, package names, paths,
  commands, or version strings.
- Separate API guarantees from implementation strategy and known limitations.
- State when a capability is only an interface boundary and a shipped instance
  does not implement every possible semantic behavior.
- Prefer short, direct technical sentences over promotional release prose.
- Use explicit Luna Flow aliases in MoonBit examples: `@lf_alg` for
  `Luna-Flow/luna-generic` and `@lf_arith` for `Luna-Flow/arithmetic`.
- Chinese should read as natural written technical Chinese. Japanese should use
  natural technical Japanese rather than literal translation.