Documentation Standards and Governance¶

This standard defines how WhiteLotusAI documentation is written, reviewed, validated, and maintained. It establishes a consistent approach to technical accuracy, security, usability, and long-term maintainability across the documentation site.

Documentation is part of the engineering lifecycle. It must describe the current implementation accurately, distinguish verified behavior from planned capabilities, and provide sufficient evidence for important technical claims.

1. Objectives¶

The documentation governance process aims to:

• Maintain accurate and consistent technical information.
• Make setup instructions, API references, and operational procedures reproducible.
• Clearly distinguish implemented, planned, and unverified capabilities.
• Reduce ambiguity in architecture, security, and integration documentation.
• Ensure changes to application behavior are reflected in the relevant documentation.
• Maintain reliable navigation, internal links, code examples, and rendered pages.

2. Writing standards¶

All documentation must use clear, professional, technically precise language.

2.1 Implementation status and evidence¶

Use explicit status language when describing features, controls, integrations, or operational capabilities.

These statuses describe different kinds of evidence. For example, a feature may be implemented without having been tested, and a passing unit test does not necessarily establish correct behavior in production.

3. Standard page structure¶

Use the following structure when it fits the page's purpose. Omit sections that do not add value rather than forcing every page into an identical template.

1. Purpose — Explain why the document exists.
2. Scope — Identify the systems, features, or workflows covered.
3. Prerequisites — State required access, dependencies, configuration, and assumptions.
4. Design or procedure — Explain the architecture, workflow, or steps.
5. Configuration and examples — Include relevant settings and reproducible examples.
6. Failure modes — Describe errors, limitations, recovery steps, and expected behavior.
7. Security considerations — Document permissions, trust boundaries, and sensitive-data handling where relevant.
8. Validation — Explain how readers can verify the documented behavior.
9. Related references — Link to authoritative supporting documentation.
10. Ownership and review — Identify the responsible owner and review date when required.

3.1 Headings and formatting¶

• Use one top-level heading (#) per page.
• Organize sections with sequential heading levels.
• Use bold text sparingly for important terms, warnings, and key actions.
• Use inline code for filenames, environment variables, commands, API paths, and identifiers.
• Use fenced code blocks with language identifiers for source code and commands.
• Use tables for concise comparisons and structured reference information.
• Use ordered lists for sequential procedures and unordered lists for independent items.
• Use admonitions only when they communicate meaningful information, such as warnings, prerequisites, important limitations, or tips.
• Avoid decorative emojis, excessive callouts, and unnecessary visual elements in technical reference pages.

4. File naming and organization¶

Use lowercase filenames with hyphens. Choose names that describe the document's subject clearly and remain stable as the content evolves.

Organize documents according to the existing documentation structure and navigation defined in zensical.toml. Before creating a new page, check whether the content belongs in an existing document or should be linked from one.

5. Front matter and metadata¶

Use YAML front matter when supported by the site's configured Markdown extensions and when metadata improves discoverability or maintenance.

For example:

---
title: API Authentication
description: Authentication requirements and token-handling behavior for the WhiteLotusAI API.
---

Metadata requirements:

• Use a concise, descriptive title.
• Provide a meaningful description for important reference and governance pages.
• Keep metadata values accurate and aligned with the page content.
• Do not introduce custom metadata fields unless the documentation tooling or an established workflow uses them.
• Verify that the configured site generator accepts the front matter and renders the page correctly.

Front matter does not replace navigation configuration. Confirm that the page is discoverable through the appropriate navigation entry.

6. Code examples and configuration¶

Code examples must be accurate, minimal, and safe to reproduce.

6.1 Code block conventions¶

Specify the language for syntax highlighting.

# Example: validate the documentation build
zensical build

Use bash for shell commands, python for Python, typescript for TypeScript, json for JSON, yaml for YAML, and mermaid for supported diagrams.

Commands shown above are examples of documentation conventions. Confirm the appropriate command for the repository's installed tooling before treating it as a verified project procedure.

6.2 Configuration safety¶

• Never include real credentials, production tokens, private keys, or personally identifiable information.
• Use clearly marked placeholders such as YOUR_API_TOKEN.
• Identify required and optional configuration values.
• Explain relevant defaults, accepted formats, and security implications.
• Avoid commands that delete, overwrite, migrate, or expose data unless their effects and prerequisites are explained.
• Test commands in an appropriate environment before labeling them as verified procedures.

6.3 Content tabs and reusable examples¶

Use content tabs only when they improve comparison or reduce duplication. For example, separate platform-specific instructions may be presented as tabs when each alternative is complete and independently understandable.

python --version

python --version

The examples above demonstrate presentation conventions; they are not a substitute for repository-specific setup instructions.

Avoid tabs when readers need to follow every step in sequence or when hiding important security information could cause mistakes.

7. Diagrams, images, and visual elements¶

Use diagrams when they explain architecture, dependencies, trust boundaries, workflows, or decision points more effectively than prose alone.

7.1 Diagram standards¶

• Use Mermaid for supported source-controlled diagrams.
• Give nodes concise, meaningful labels.
• Use explicit decision nodes when branches have different outcomes.
• Keep diagrams small enough to remain readable on desktop and mobile screens.
• Prefer standard Mermaid syntax and avoid unsupported renderer-specific features.
• Use restrained colors and ensure labels remain legible in both light and dark themes.
• Do not encode meaning through color alone.
• Ensure that diagrams agree with the documented implementation and do not imply unverified integrations or runtime behavior.

The following diagram illustrates the documentation governance process rather than asserting anything about application runtime behavior.

flowchart TD
    A["Identify documentation change"] --> B["Inspect implementation or approved requirements"]
    B --> C["Draft or update the page"]
    C --> D["Review accuracy and security"]
    D --> E["Validate links, examples, and rendering"]
    E --> F{"All checks pass?"}
    F -- "No" --> C
    F -- "Yes" --> G["Update navigation and submit for review"]
    G --> H["Approve and integrate"]

    classDef process fill:#e9e3ff,stroke:#7654b8,color:#24164a
    classDef decision fill:#fff0cc,stroke:#b78324,color:#49330a
    classDef complete fill:#d9f3e8,stroke:#31866b,color:#123f32

    class A,B,C,D,E,G process
    class F decision
    class H complete

Keep diagram styling compatible with the configured Mermaid renderer. If theme-specific colors reduce readability, prefer the site's default Mermaid theme or a tested, theme-compatible palette.

7.2 Images and icons¶

Add images only when they provide useful context, such as a UI walkthrough, deployment topology, or a relevant screenshot.

• Use repository-managed assets where practical.
• Provide meaningful alternative text for informative images.
• Crop screenshots to the relevant interface or behavior.
• Remove secrets and personal information from screenshots.
• Avoid decorative images that add no technical or instructional value.
• Use icons consistently and only when they improve scanning or recognition.

Emoji and iconography should be optional visual aids, not substitutes for descriptive text or status labels.

8. Links, references, and footnotes¶

Internal links must resolve to the intended page or section. Prefer relative links consistent with the existing documentation repository.

• Use descriptive link text, such as [Security overview](../security/overview.md).
• Avoid vague labels such as "click here."
• Check links after renaming or moving a document.
• Link to an authoritative source instead of copying lengthy material into multiple pages.
• Include external references for important third-party behavior, API contracts, or technical requirements when appropriate.
• Use footnotes for brief qualifications, clarifications, or source details that would interrupt the main explanation.

Example footnote: A passing local build confirms that the documentation can be rendered in that environment; it does not establish that every technical statement has been verified.¹

Tooltips and hover-based explanations may be used for short supplementary definitions where the configured Markdown extensions support them. Essential instructions must remain available in the main content and must not depend on hover interaction.

9. Ownership and review responsibilities¶

Every critical technical document must have a clearly identifiable responsible owner. Ownership may be assigned to a role or team rather than an individual when that is more sustainable.

The document owner is responsible for keeping content accurate, arranging reviews, and updating the page when relevant implementation changes occur.

10. Review triggers¶

Review affected documentation whenever one or more of the following changes occur:

• An API contract or request/response schema changes.
• A feature is added, modified, deprecated, or removed.
• Authentication, authorization, or session handling changes.
• An integration's permissions, OAuth scopes, or supported operations change.
• Database schemas, migrations, or persistence behavior change.
• Deployment architecture, configuration, or infrastructure requirements change.
• A security incident reveals missing or inaccurate guidance.
• A defect demonstrates that a documented procedure is incorrect.
• Dependencies, tooling, or supported runtime versions change.
• Navigation, Markdown extensions, or documentation build configuration changes.

Documentation updates should be included in the same change where practical. If they must be handled separately, record the outstanding work and assign an owner.

11. Quality assurance checklist¶

Use this checklist during review and before integrating a documentation change.

Content and technical accuracy¶

• Technical statements have appropriate evidence.
• Implemented, planned, tested, and unverified behavior is distinguished accurately.
• Prerequisites, assumptions, and limitations are explicit.
• Code examples and configuration snippets are syntactically valid.
• Commands have been reviewed for safety.
• No secrets or sensitive data are exposed.
• Security implications and failure modes are documented where relevant.

Navigation and rendering¶

• The page uses the expected filename and location.
• Required metadata is present and valid.
• Navigation includes the page where appropriate.
• Internal links and anchors resolve.
• Code blocks, tables, admonitions, tabs, and diagrams render correctly.
• Images have appropriate alternative text.
• Light and dark themes remain readable where both are supported.
• The documentation build completes successfully.

Review and maintenance¶

• The responsible owner or reviewer is identified where required.
• Related pages are updated or linked.
• The implementation or approved requirements have been checked.
• Outstanding verification gaps are recorded.
• The review date or change history is updated when required by the project's workflow.

12. Definition of done¶

A documentation change is complete when all applicable conditions below have been satisfied:

1. The content has been reviewed for clarity, correctness, and scope.
2. Important technical claims are supported by appropriate evidence.
3. Code samples and commands have been reviewed and validated to the extent claimed.
4. Security-sensitive information and operational risks have been considered.
5. Navigation, links, metadata, and rendered content have been checked.
6. The documentation build passes in the intended environment.
7. Required ownership and approval steps are complete.
8. Remaining limitations or verification gaps are explicitly recorded.

A successful build alone is not sufficient to establish technical accuracy, security effectiveness, or production readiness.

13. Related documentation¶

Use the following pages as applicable:

• Documentation audit — findings and follow-up actions from the documentation quality review.
• Security overview — security principles and verification expectations.
• Threat model — documented risks and trust boundaries.
• Testing strategy — quality assurance objectives and verification expectations.

Review these links against the current repository structure before merging changes.

Governance principle: Documentation should be clear enough to use, accurate enough to trust, and evidence-based enough to audit.