Documentation Standard

This document defines the standard used to write and organize SARA documentation in Markdown for Material for MkDocs.

Core principles

Single source of truth (General Features)

If information is reusable across many parts of SARA, it belongs in General Features and should be referenced from other pages, not duplicated.

Typical General Features documents include:

Common UI behavior (tables, filters, dynamic columns, naming conventions)
Status (system-wide status guidance)
Logs & History (traceability/auditing)
Workflows & Pipelines (record lifecycle model)
Notifications & Alerts (email notifications behavior)
Permissions & Access (conceptual permissions guidance)
Control Panel (configuration management)

Rule: If you feel you are writing the same explanation twice, move it to general_features/ and link to it.

Documentation organization model

Documentation is organized by business domain (e.g., Sales, HR, Procurement, Inventory), not by where items appear in the SARA menu. UI grouping can change in Control Panel; documentation should remain stable.

Split each domain into feature sections

Each domain is divided into feature sections (a coherent capability users recognize), such as:

Sales → Quotes
HR → Vacations
Procurement → Purchasing workflow
Inventory → Inventory operations

A feature section may include one or more transactions (screens/URLs).

Standard document set per feature

Each feature section should contain these files:

transactions.md
- Describes the transactions (URLs/screens) that make up the feature.
- Explains what each screen is for and its main tabs/areas.
workflow.md
- Describes the end-to-end process (handoffs, statuses used, notifications, exceptions).
- References the global workflow model instead of repeating it.
permissions.md
- Lists permission labels as shown in SARA and explains what each grants.
- Uses a table format for clarity.

To avoid repeated names in the MkDocs navigation (e.g., Vacations → Vacations — Transactions), use:

Front matter title: a generic label such as Transactions, Workflow, or Permissions.
First H1 (# ...): include the feature name, for example:
- # Vacations — Transactions
- # Vacations — Workflow
- # Vacations — Permissions

This keeps the menu clean while still making the page context clear.

Optional: `index.md` per feature

Only create a index.md inside a feature folder when you need a landing page. Typical uses:

The feature is large and benefits from a summary page.
You want a “quick start” overview and entry points to transactions/workflow/permissions.

Optional: domain `index.md` for large domains

For very large domains (HR, Procurement, Inventory), a domain-level index can provide:

A summary of what the domain supports.
Links to feature sections.
“Implemented” vs “Planned/Upcoming” overview.

Folder structure

Use a folder per domain and per feature:

docs/
  sales/
    quotes/
      # index.md (optional)
      permissions.md
      transactions.md
      workflow.md
  procurement/
    purchasing/
      permissions.md
      transactions.md
      workflow.md
    inventory/
      permissions.md
      transactions.md
      workflow.md

File naming inside feature folders

Inside a feature folder, prefer generic names:

permissions.md
transactions.md
workflow.md

Avoid globally named files like quote_workflow.md once they live inside a feature folder.

Content standards

Transactions pages

Use a feature-specific H1 (e.g., # Vacations — Transactions) while keeping the front matter title generic (e.g., title: Transactions).
Do not place long transaction descriptions inside Material tabs (===) if they contain many headings.
Use normal headings so the right-side TOC is useful:
- ## Quotes
- ## Quote Engine
- ### What you will see
- ### What you can do here

Use tabs (===) only for short comparisons (e.g., User/Admin, Current/Planned).

Workflow pages

Use a feature-specific H1 (e.g., # Vacations — Workflow) while keeping the front matter title generic (e.g., title: Workflow).
Use a workflow step summary at the start (recommended via !!! abstract) and clean headings per step.
Avoid numbering headings. Use numbered lists inside step sections if needed.
Reference general_features/workflows_and_pipelines.md instead of repeating the global lifecycle model.
Include Setup & dependencies when configuration is required for the workflow to function (e.g., rules in Control Panel, required relationships in Collaborators).
Include Exceptions & operational notes for special flows and non-standard behavior (e.g., HR direct assignment, edit-approved restarts flow, calendar visibility rules).

Recommended structure:

## Overview
## Roles involved
## Status lifecycle (only statuses used in this workflow)
## Workflow (with !!! abstract step summary)
- ### <Step title> (no numbers)
## Notifications (if applicable)
## Setup & dependencies (if applicable)
## Exceptions & operational notes (if applicable)
## Permissions (reference to permissions.md)
## Related resources

Permissions pages

Use a feature-specific H1 (e.g., # Vacations — Permissions) while keeping the front matter title generic (e.g., title: Permissions).
Document permissions as labels (as shown in SARA), typically grouped by transaction.
Prefer tables:

Permission	Grants access to
View	Access general transaction with records

If a single permission group covers multiple transactions, document it under one section and clarify scope.

Planned / Upcoming content

Document only what exists today as Implemented.
Place future behavior under a clearly marked section such as:

Planned / Upcoming

This behavior is planned but not implemented yet.

Avoid writing planned behavior as if it already works.

Material for MkDocs formatting rules

Lists and nesting

Always include a blank line before lists.
Nested lists must indent child bullets by 4 spaces under the parent bullet.

Correct example:

Parent item
- Child item
- Child item

Avoid forced line breaks

Avoid using “two trailing spaces” to force line breaks, as it can cause inconsistent rendering. Prefer proper paragraph breaks.

Use admonitions consistently

Use Material admonitions for emphasis:

!!! note for important general notes
!!! tip for practical guidance
!!! warning for risk or restricted actions
!!! info for clarifications or planned/upcoming
!!! abstract for summaries (especially workflow steps)

Linking standards

Reference general features instead of duplicating

When a page needs to mention global behavior, link to the authoritative page:

Common UI behavior → general_features/common_features.md
Record lifecycle concepts → general_features/workflows_and_pipelines.md
Status explanation → general_features/status.md
Logging → general_features/logs_and_history.md
Notifications → general_features/notifications_and_alerts.md
Permissions concept → general_features/permissions_and_access.md

Link sibling documents in each feature

Each feature should cross-link:

Transactions ↔ Workflow ↔ Permissions

Relative paths must match folder depth

Feature folders are often nested (e.g., sales/quotes/), so general features links typically become:

../../general_features/...

nav:
  - Sales:
      - Quotes:
          - Permissions: sales/quotes/permissions.md
          - Transactions: sales/quotes/transactions.md
          - Workflow: sales/quotes/workflow.md
  - Procurement:
      - Inventory:
          - Permissions: procurement/inventory/permissions.md
          - Transactions: procurement/inventory/transactions.md
          - Workflow: procurement/inventory/workflow.md
      - Purchasing:
          - Permissions: procurement/purchasing/permissions.md
          - Transactions: procurement/purchasing/transactions.md
          - Workflow: procurement/purchasing/workflow.md

Maintenance guidelines

If you change behavior in SARA, update the closest authoritative document:
- General behavior → update general_features/
- Feature-specific behavior → update the relevant feature folder
When you find repetition, move common content upward into General Features.
Keep “Implemented” and “Planned / Upcoming” clearly separated to avoid confusion.

Page templates

This section provides copy/paste templates for the three standard pages inside each feature folder.

Template: transactions.md

---
title: Transactions
---

# <Feature> — Transactions

## Overview
Write 1–3 lines describing what this feature is and what it enables. Do not list the transactions here.

For the end-to-end process, see: [Workflow](workflow.md).

!!! note
    For common UI patterns used across SARA (tables, filters, dynamic columns, naming conventions), see:
    [Common Features](../../general_features/common_features.md)

---

## <Transaction 1>

### Overview
Short description of what this transaction is for.

### What you will see

- Key lists, cards, or summaries visible in the transaction.

### What you can do here

- Key actions available in this transaction.

### Tabs (Optional, only if needed)

- <Tab name>
    - Short description of what the tab is used for.

---

## <Transaction 2>

### Overview
Short description of what this transaction is for.

### What you will see

- Key lists, cards, or summaries visible in the transaction.

### What you can do here

- Key actions available in this transaction.

### Tabs (Optional, only if needed)

- <Tab name>
    - Short description of what the tab is used for.

---

## Permissions

!!! note "Permissions"
    Access and actions are permission-driven.
    See: [Permissions](permissions.md)

---

## Related resources

- [Workflow](workflow.md)
- [Permissions](permissions.md)
- [Common Features](../../general_features/common_features.md)
- [Workflows & Pipelines](../../general_features/workflows_and_pipelines.md)
- [Status](../../general_features/status.md)
- [Logs & History](../../general_features/logs_and_history.md)
- [Notifications & Alerts](../../general_features/notifications_and_alerts.md)

Template: workflow.md

---
title: Workflow
---

# <Feature> — Workflow

## Overview
Write 2–5 lines describing the end-to-end workflow and its purpose.

!!! note
    This feature follows SARA’s standard record lifecycle model.

    See: [Workflows & Pipelines](../../general_features/workflows_and_pipelines.md)

---

## Roles involved

- **<Role 1>**
    - <Responsibility>
- **<Role 2>**
    - <Responsibility>

---

## Status lifecycle
List only the statuses used in this workflow (as shown in the UI).

- `<STAT>` — <Meaning>
- `<STAT>` — <Meaning>

!!! info
    For system-wide status guidance, see:
    [Status](../../general_features/status.md)

---

## Workflow

!!! abstract "Workflow steps"
    1. <Step 1 summary>
    2. <Step 2 summary>
    3. <Step 3 summary>

### <Step title>
Describe the step in a short paragraph.

- Key actions
    - <Action>
    - <Action>

### <Step title>
Describe the step in a short paragraph.

---

## Notifications (Optional)
Describe which email notifications are sent and when.

!!! note
    For global notification behavior, see:
    [Notifications & Alerts](../../general_features/notifications_and_alerts.md)

---

## Setup & dependencies (Optional)
Describe required configuration or data relationships that must exist for this workflow to function.

**Examples**:
- Vacation rules configured in **Control Panel** (Internal Company settings).
- Direct manager relationships configured in **Collaborators**.

---

## Exceptions & operational notes (Optional)
List special cases that deviate from the standard flow.

**Examples**:
- HR direct assignment creates an approved record without approvals and without notifications.
- Editing an approved request restarts the approval flow.
- Some approved records may not appear in planning calendars by design.

---

## Permissions

!!! note "Permissions"
    Access and actions are permission-driven.

    See: [Permissions](permissions.md)

---

## Related resources

- [Transactions](transactions.md)
- [Permissions](permissions.md)
- [Common Features](../../general_features/common_features.md)
- [Workflows & Pipelines](../../general_features/workflows_and_pipelines.md)
- [Status](../../general_features/status.md)
- [Logs & History](../../general_features/logs_and_history.md)
- [Notifications & Alerts](../../general_features/notifications_and_alerts.md)

Template: permissions.md

---
title: Permissions
---

# <Feature> — Permissions

## Overview
This page documents the permissions used in the <Feature> feature. Permissions determine which transactions a user can access and which actions are available.

For general access concepts, see: [Permissions & Access](../../general_features/permissions_and_access.md)

---

## Permissions by transaction

=== "<Transaction 1>"

    | Permission | Grants access to |
    |---|---|
    | <permission label> | <Explain what the user can see/do and where it appears in the UI.> |
    | <permission label> | <Explain what the user can see/do and where it appears in the UI.> |

=== "<Transaction 2>"

    | Permission | Grants access to |
    |---|---|
    | <permission label> | <Explain what the user can see/do and where it appears in the UI.> |

---

## Typical role mapping (recommended)

- **<Role name>**
    - <permission label>
    - <permission label>

- **<Role name>**
    - <permission label>

---

## Troubleshooting access

- If a transaction is missing from the menu or a tab/button is not visible, it is usually due to missing permissions.
- If a permission depends on another one (for example, “administration requires view”), document that dependency explicitly.
- Request access from your supervisor or system admin.

For system-wide troubleshooting, see: [Permissions & Access](../../general_features/permissions_and_access.md)

---

## Related resources

- [Transactions](transactions.md)
- [Workflow](workflow.md)
- [Permissions & Access](../../general_features/permissions_and_access.md)
- [Control Panel](../../general_features/control_panel.md)

Documentation Standard

Core principles

Single source of truth (General Features)

Documentation organization model

Organized by domain, not by UI menu position

Split each domain into feature sections

Standard document set per feature

Page titles (MkDocs navigation)

Optional: `index.md` per feature

Optional: domain `index.md` for large domains

Folder and navigation conventions

Folder structure

File naming inside feature folders

Content standards

Transactions pages

Workflow pages

Permissions pages

Planned / Upcoming content

Material for MkDocs formatting rules

Lists and nesting

Avoid forced line breaks

Use admonitions consistently

Linking standards

Reference general features instead of duplicating

Link sibling documents in each feature

Relative paths must match folder depth

Example navigation (MkDocs)

Maintenance guidelines

Page templates

Template: transactions.md

Template: workflow.md

Template: permissions.md

Documentation Standard

Core principles

Single source of truth (General Features)

Documentation organization model

Organized by domain, not by UI menu position

Split each domain into feature sections

Standard document set per feature

Page titles (MkDocs navigation)

Optional: index.md per feature

Optional: domain index.md for large domains

Folder and navigation conventions

Folder structure

File naming inside feature folders

Content standards

Transactions pages

Workflow pages

Permissions pages

Planned / Upcoming content

Material for MkDocs formatting rules

Lists and nesting

Avoid forced line breaks

Use admonitions consistently

Linking standards

Reference general features instead of duplicating

Link sibling documents in each feature

Relative paths must match folder depth

Example navigation (MkDocs)

Maintenance guidelines

Page templates

Template: transactions.md

Template: workflow.md

Template: permissions.md

Optional: `index.md` per feature

Optional: domain `index.md` for large domains