Write for the reader’s next task
An orientation, a how-to and an API reference answer different questions. Documentation identifies its purpose and intended readers so administrators and integrating developers can find the depth they need.
Example — Two readers, two paths
An administrator wants to invite a colleague. An integration developer needs the API contract. Their guides can share underlying facts while taking different routes through the explanation.
For engineers
The engine’s orientation definition demonstrates the distinction. This selected declaration is framework content metadata, not a standalone application registration:
'technical-documentation:unit/application-orientation': {
kind: TechnicalDocumentationUnitKind.ORIENTATION,
readerAudiences: [
TechnicalDocumentationReaderAudience.APPLICATION_OPERATIONS_STAFF,
TechnicalDocumentationReaderAudience.CONSUMING_INTERNAL_SERVICE,
TechnicalDocumentationReaderAudience.EXTERNAL_INTEGRATION_DEVELOPER,
TechnicalDocumentationReaderAudience.ORGANIZATION_ADMINISTRATOR,
TechnicalDocumentationReaderAudience.ORGANIZATION_INTEGRATION_DEVELOPER,
],
accessClass: TechnicalDocumentationAccessClass.PUBLIC,
applicabilityRequirements: [],
The vocabularies come from @wildo-ai/saas-specifications/technical-documentation. Kind answers what the document does; reader audiences answer whom it serves; access class and applicability control different publication decisions. Audience is not an authorization role or a private-content gate.
Compose a reading path, not a type list
The engine content catalogue joins this metadata to authored Markdown and related units. The managed renderer builds the portal’s categorized navigation and authored journeys. An application supplies its product/resource facts through the supported projection path; do not add a new unit to an arbitrary local file and assume the managed renderer will publish it.
Use an orientation to explain the product, a how-to for a concrete task and reference material for exact contracts. Verify that the generated navigation leads readers through that sequence and that each page answers its own question without relying on internal framework terminology.