Writing Guide

Standards for all Smartflow documentation. Follow these rules to maintain consistency across the docs site.

---

Grammar Rules

1. Active voice. "Smartflow extracts fields" not "Fields are extracted by Smartflow."
2. Present tense. "Click Export" not "You will click Export."
3. Second person. Address the reader as "you" in user docs.
4. Serial comma. "Borrowers, lenders, and agents."
5. Sentence case for headings. "Getting started with Smartflow" not "Getting Started With Smartflow." Exception: proper nouns (LoanIQ, Smartflow).
6. No contractions in formal docs. "Do not" instead of "Don't" in specs and compliance content. Contractions are acceptable in user guides and training.

---

Tone per Audience

Audience	Voice	Key Principles
End users	Plain English, task-oriented, reassuring	Numbered steps, short sentences, outcome-first. Avoid jargon.
Support	Precise, diagnostic, direct	Symptom → cause → resolution → escalation. Never ambiguous.
Sales / Partners	Confident, value-first, consultative	Problem → solution → proof → next step. No deep implementation details.
Designers	Structured, component-referenced, unambiguous	Spec → tokens → states → interactions. No narrative prose.
Eval / QA	Precise, measurable, unambiguous	Input → expected output → scoring criteria. No vague acceptance criteria.
Demo scripts	Confident, narrative, human	Time-blocked talking track + screen actions. Never read bullets verbatim.
Scoping	Curious, neutral, discovery-mode	Question → why we ask → signal interpretation. No overselling.

---

Terminology Consistency

Always use terms as defined in the Terminology Glossary. Key rules:

Use This	Not This
Smartflow	SmartFlow, Smart Flow
LoanIQ	Loan IQ, loaniq
credit agreement	loan document (in formal context)
extraction	parsing, reading
evidence-linked	AI-grounded, source-mapped
covenant monitoring	covenant tracking
HITL (Human-in-the-Loop)	manual review (on first reference, spell out)

---

Formatting Rules for Docusaurus

Frontmatter

Every markdown file must have YAML frontmatter. See COPILOT-CONTEXT.md for the schema.

Admonitions

Use Docusaurus admonition syntax:

:::note
Informational callout for supplementary context.
:::

:::tip
Helpful advice or best practice.
:::

:::info
Important context the reader should know.
:::

:::warning
Something that could cause problems if ignored.
:::

:::danger
Critical warning — data loss, security risk, or breaking change.
:::

Code Blocks

Always specify the language:

```json
{ "key": "value" }
```

Tabs

Use Docusaurus tabs for multi-option content (e.g., different OS instructions):

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="azure" label="Azure" default>
    Azure-specific instructions.
  </TabItem>
  <TabItem value="on-prem" label="On-Premise">
    On-premise instructions.
  </TabItem>
</Tabs>

Links

• Use relative markdown links: [LoanIQ Export](./loaniq-export-guide.md).
• Cross-link related documents whenever relevant.
• Never use absolute URLs for internal docs.

Images

• Store in site/static/img/ with descriptive names.
• Always include alt text.
• Use PNG for screenshots, SVG for diagrams.