Skip to content

SmrtHub Documentation Policy v1.0

Canonical governance for documentation across SmrtHub surfaces (MKDocs/README, XML/docstrings, inline comments). Defines ownership, content scope, and update expectations required for enterprise-grade accuracy.

1. Purpose

  • Provide a single source of truth describing how documentation is authored, organized, and maintained.
  • Eliminate redundant or conflicting explanations across READMEs, docstrings, and comments.
  • Ensure future automation (auto-import of docstrings into MKDocs) has predictable, high-quality input.

2. Documentation Surfaces & Responsibilities

Surface Primary Audience Authoritative Content Tooling Consumption
MKDocs site + repository READMEs Operators, architects, onboarding, support Architectural narratives, workflows, configuration/log locations, troubleshooting, release notes Rendered by MkDocs from MKDocs/docs/**; source files typically live under README.Files/** or component folders
Docstrings (Python) / XML doc comments (C#) Developers, code completion, API docs Function/class/module contracts, parameters, returns, exceptions, invariants, usage hints Python __doc__ and C# XML documentation; eligible for future mkdocstrings or Sandcastle/DocFX pipelines
Inline comments (# / // / /* */) Future maintainers reading implementation Justification for non-obvious decisions, algorithm notes, TODOs with tracking IDs Not ingested by doc tooling; remains in source only

3. MKDocs & README Standards

  1. Canonical location: Maintain per-component README under the component root (e.g., SmrtApps/<Component>/README.md). Mirror or include the content inside MKDocs/docs/components/ via symlink/include or manual copy; MKDocs is the user-facing portal.
  2. Recursive coverage: Every subdirectory that contains production code, scripts, or documentation assets must include a README (or adopt an inherited README via explicit include) describing its purpose, key files, and links to higher-level guidance. Subdirectories that only contain generated artifacts or build outputs are exempt but must be identified in the parent README.
  3. Required sections (minimum template):
  4. Overview & responsibilities
  5. Dependencies / integrations (cross-runtime notes where relevant)
  6. Configuration & log paths referencing Operational Data Policy slugs
  7. Runtime flows / operational workflows
  8. Testing & validation expectations
  9. Support bundle / diagnostics touchpoints
  10. Policy references: Link to files in docs/policies/** instead of duplicating policy text.
  11. Change tracking: Record release or behavior changes in MKDocs (not in code comments). For significant updates include a "Changelog" or "Notable Updates" section.
  12. Generated docs: Auto-generated API references belong under docs/components/auto/. When re-enabling auto-import, ensure source docstrings follow the formats described in section 4.

4. Docstrings & XML Documentation

  1. Docstring coverage requirement: All files written in docstring-capable languages (currently Python modules, classes, and functions; C# public/internal APIs with XML documentation) must include compliant documentation. Treat uncovered members as policy violations unless explicitly excluded in a component README with rationale (e.g., generated code, test doubles).
  2. Python docstrings:
  3. Use triple-quoted strings directly under module/class/function definitions.
  4. Prefer reStructuredText (reST) field lists for parameters and returns (works with mkdocstrings, Sphinx, IDEs).
  5. Include: concise summary line, detailed description (optional), :param, :returns:, :raises: entries, thread-safety or side-effect notes, and micro examples when essential.
  6. Avoid duplicating MKDocs narratives; reference high-level concepts by name (e.g., "See Smrt.Logging canonical schema").
  7. C# XML doc comments:
  8. Use /// XML comments on public types and members; optional on internal APIs when they interface cross-assembly.
  9. Provide <summary>, <param>, <returns>, <remarks>, <exception> elements. <remarks> can link to MKDocs sections by relative URL.
  10. XML comments compile into documentation metadata when /doc is enabled, supporting DocFX or Sandcastle outputs.
  11. Parity expectations:
  12. Surface-specific nuances (async semantics, thread requirements, cross-runtime coordination) must appear in both Python docstrings and C# XML comments for analogous APIs.
  13. When behavior diverges between runtimes, note the difference explicitly in each runtime’s docstring/comment and mention the canonical MKDocs reference.

5. Inline Comments (Non-docstring)

  1. Use sparingly: Restrict inline comments to cases where code intent cannot be inferred from naming or structure.
  2. Content rules:
  3. Document workarounds, algorithmic nuances, or rationale that, if removed, would reintroduce bugs.
  4. Include tracking IDs (TODO(#issue-id):) when referencing planned work.
  5. Do not restate what MKDocs or docstrings already cover; when a comment duplicates higher-level docs, delete or replace with a reference link.
  6. No doc tooling consumption: Inline comments are not parsed into documentation. Critical user-facing information must live in docstrings or MKDocs.

6. Avoiding Duplication & Conflicts

Scenario Correct Location Notes
API signature, parameter meaning Docstring / XML doc Keep concise; reference MKDocs section when context is broad
Overall component workflow MKDocs README Link to policy docs; maintain diagrams/assets under MKDocs/docs/assets/
Configuration or log path MKDocs (with pointers to Operational Data Policy) Mention only summarized references in code comments
Non-obvious algorithm tweak Inline comment Provide rationale + ticket reference
Error handling contract Docstring / XML doc Ensure docstring matches actual exceptions thrown

7. Update Workflow

  1. When changing behavior, update the source docstring/XML comment first to keep API references accurate.
  2. Reflect narrative/operational changes in the relevant README or MKDocs page in the same PR.
  3. If automation pipelines regenerate docs/components/auto/*.md, run the generator script and commit diffs.
  4. PR checklist must include:
  5. Docstrings/XML comments updated for API changes
  6. MKDocs/README content updated (or confirmed unaffected)
  7. Inline comments audited to ensure no stale references

8. Tooling & Automation Notes

  • Current state: MKDocs builds from Markdown under MKDocs/docs/**. Docstrings are not yet auto-imported.
  • Future enablement: When enabling mkdocstrings or similar, point it at modules annotated for export. Docstring compliance (section 4) guarantees renderable output.
  • Validation: Consider adding lint checks (e.g., pydocstyle, docformatter, Roslyn analyzers for XML documentation) to enforce presence/quality.

9. Governance

  • Maintainers: Architecture & Runtime Platform team.
  • Version bumps: Update this file when policy changes; reflect version in filename and MKDocs policies index.
  • Disputes or deviations require architecture review sign-off recorded in MKDocs docs/policies/ change log.

Maintainers: Architecture & Runtime Platform Team Initial Release: v1.0