Skip to main content

Documentation Standard

This document defines the standard structure and conventions for SMDS documentation. All new documentation should follow this template to ensure consistency, clarity, and usefulness for stakeholders and engineers.

Reference implementation: Vendor Onboarding

Document Structure​

Every functional or process document should include the following sections, in order:

1. Document Purpose​

Brief statement of what the document covers and why it exists.

This document describes [topic]. It is intended for [audience] who need to [goal].

2. Executive Summary​

2–4 sentences for stakeholders who need the high-level view. Answer: What is this? Why does it matter? What is the outcome?

3. Business Context (Optional)​

AspectDescription
ProblemWhat problem does this solve?
SolutionHow does it solve it?
ScopeWhat is in scope? What is out of scope?

4. Audience​

Explicitly list who should read the document:

  • Business stakeholders — Understand process and outcomes
  • Product owners — Understand flows and decision points
  • Engineers — Implement or integrate
  • Data stewards — Configure rules and policies

5. Prerequisites​

What must be true before the process can start? (User roles, inputs, system state.)

6. Main Content​

  • Use tables for structured data (steps, options, statuses)
  • Use Mermaid diagrams for flows and state machines
  • Use numbered steps for sequential processes
  • Use bullets for unordered lists

7. Key Decision Points​

DecisionOwnerOptionsOutcome
............

8. Error Handling​

ErrorCauseUser Action
.........

9. Glossary​

Define acronyms and domain terms on first use. Include a glossary table for documents with 3+ abbreviated terms.

Links to upstream/downstream docs, technical design, API reference.

Conventions​

Terminology​

  • Consistent naming — Use the same term throughout (e.g., "Vendor ID" not "Vendor Id" or "vendor_id" in prose)
  • Acronyms — Spell out on first use: "VMDM (Vendor Master Data Management)"
  • Status codes — Use consistent format: PENDING (P), ACTIVE (A)

Tables​

  • Use tables for comparisons, steps, status codes, and configurations
  • Include headers; keep cells concise
  • Use | alignment for readability where helpful

Diagrams​

  • Mermaid — For flows, state machines, sequences (version-controlled, readable in source)
  • Draw.io — For complex diagrams requiring visual editing; export SVG for docs
  • Use relative links within the same doc section: [Record Initiation](./record-initiation)
  • Use absolute paths for cross-domain: [API Reference](/api-reference)
  • Use anchor links for in-doc navigation: #detailed-flow

Code & Technical References​

  • Reference API specs, not inline request/response examples (unless critical)
  • Link to API Reference for interactive specs

Checklist for New Documents​

Before publishing, verify:

  • Document Purpose and Audience are stated
  • Executive Summary is present and clear
  • Prerequisites are documented
  • Decision points and error handling are covered
  • Glossary includes all acronyms used
  • Related Documentation links are current
  • Diagrams are present for complex flows
  • Tables are used for structured data
  • Terminology is consistent throughout

Multi-Page Documentation​

For processes spanning multiple pages (e.g., Vendor Onboarding):

  1. Overview — Purpose, summary, process stages, actor paths, glossary
  2. Stage / Sub-topic pages — Detailed flow, prerequisites, error handling per stage
  3. Lifecycle / Status — State machine, downstream impact, transition rules

Use a Diagram Index in the overview to help readers navigate.

Example: Minimal Template​

---
sidebar_position: N
---

# [Feature Name]

## Document Purpose

This document describes [X]. It is intended for [audience].

## Executive Summary

[2-4 sentences]

## Audience

- Stakeholders
- Engineers

## Prerequisites

| Prerequisite | Description |
|--------------|-------------|
| ... | ... |

## [Main Content]

...

## Key Decision Points

| Decision | Owner | Options | Outcome |
|----------|-------|---------|---------|
| ... | ... | ... | ... |

## Error Handling

| Error | Cause | User Action |
|-------|-------|-------------|
| ... | ... | ... |

## Glossary

| Term | Definition |
|------|------------|
| ... | ... |

## Related Documentation

- [Link](./path)
Was this page helpful?