Documentation and quality
A partner extension must be understandable without reading its code. Documentation explains the public contract and its guarantees; it must neither invent capabilities nor copy internal implementation details.
Sources of truth
Apply the following rule: missing reliable information > invented precision.
- Ormuz-owned parameters and outputs are documented from their actual contract;
- provider objects and fields come from the provider's official documentation or schema;
- an Ormuz normalization may document additional semantics only when explicitly defined by the contract;
- when a field remains ambiguous, leave its help incomplete rather than synthesizing a misleading definition.
Describe fields and outputs
A good description explains what the value represents, when it is available, which units or cardinalities apply, and what guarantee the consumer can rely on.
Avoid tautologies such as “status: the status” or “amount: the amount”. For a provider output, clearly distinguish submission, intermediate processing, and final outcome when the provider separates them.
An example must not become a normative rule. Executable limits, enums, and invariants belong to the structural contract and should be generated or validated from their canonical source.
Errors and warnings
- document the errors a user or Agent can actually handle;
- do not expose a provider's raw message as a stable contract without security validation;
- keep warnings in the shared observability channel, not in business outputs;
- if a result is incomplete and the consumer needs to know it, encode that incompleteness in the result contract rather than only in an operator warning.
Localisation
Technical identifiers remain stable; labels, descriptions, examples, and user-facing messages are localizable. Do not place editorial text in a structure that must remain serializable and locale-independent.
Translations must preserve the same business guarantee. A translation that is vaguer or stronger than the source creates contract drift.
Choose the right documentation rendering
Choose a format suited to the information: a diagram to explain a flow, a code example to illustrate an integration, or a table to compare options.
| Content type | Rendu attendu |
|---|---|
| Flow, architecture, relationship, or conceptual sequence | Compact diagram that is readable without zooming. |
| CLI command or code excerpt | Code excerpt with the language indicated. |
| JSON strict | Valid, readable JSON example. |
| HTTP call with JSON payload | Method and URL, followed by the JSON request body. |
| Exhaustive contract, matrix, or comparison | Table. |
| Parallel choices | Cartes comparatives. |
| Ordered journey | List of steps. |
| Invariant, guarantee, or important warning | Clearly identified callout. |
Each example must be readable and include the context needed to use it. Prefer a diagram over a complex ASCII schematic; a simple relationship can be explained in text or a table.
Review checklist
- Are the use case and the moment when the contribution should be used explicit?
- Do the parameters, outputs, cardinalities, and limits match the extension's behavior?
- Are external effects and intermediate results distinguished?
- Are authority, permissions, classification, and risk level kept distinct?
- Are errors and retry behaviors safe and actionable?
- Are provider sources official or explicitly established by Ormuz?
- Does the documentation explain observable behavior without requiring the reader to know the extension code?