Style Guide

This style guide establishes the writing standards for all DPO2U documentation. It ensures consistency, clarity, and accessibility across every page — whether written by a single contributor or a distributed team.

Voice and Tone

Principles

Principle	Do	Don't
Active voice	"The agent verifies the attestation."	"The attestation is verified by the agent."
Second person	"You can configure the MCP server…"	"The user can configure the MCP server…"
Present tense	"The contract stores a hash."	"The contract will store a hash."
Direct	"Run npm install."	"You might want to consider running npm install."
Inclusive	"Before you begin, ensure…"	"Obviously, you need to…"

Audience

Write for developers and technical architects who are evaluating or integrating DPO2U. Assume familiarity with blockchain concepts, APIs, and command-line tools. Do not assume familiarity with Midnight-specific terminology — always define it on first use.

Terminology

Use the following terms consistently throughout the documentation:

Term	Usage	Notes
Midnight Network	Always capitalize both words	Never abbreviate to "Midnight" alone in headings
Compact	Capitalize as a proper noun	Midnight's smart contract language
$NIGHT	Always include $ prefix	The economy/staking token on Cardano
$DUST	Always include $ prefix	Non-transferable execution token on Midnight
zk-SNARKs	Lowercase zk, hyphen, uppercase SNARK	Zero-Knowledge Succinct Non-Interactive Argument of Knowledge
DID	Uppercase abbreviation	Decentralized Identifier (e.g., did:midnight:agent:auditor)
Attestation	Capitalize when referring to DPO2U's on-chain compliance record	Lowercase for general concept
MCP	Model Context Protocol	Always expand on first use per page
LGPD	Lei Geral de Proteção de Dados	Brazilian data protection regulation
GDPR	General Data Protection Regulation	EU data protection regulation

Formatting Standards

Headings

• Use sentence case for all headings: "Getting started with agents" not "Getting Started With Agents"
• Use H2 (##) for major sections, H3 (###) for subsections
• Never skip heading levels (e.g., H2 directly to H4)
• Keep headings concise — under 8 words when possible

Code blocks

Always specify the language for syntax highlighting:

```typescript
const status = await checkCompliance(companyId);
```

Use inline code for:

• File names: docusaurus.config.js
• Function names: checkCompliance()
• CLI commands: npm run build
• Variable names, contract names, and paths

Links and cross-references

• Use descriptive link text: Architecture overview, not click here
• Always use relative paths for internal links: /docs/intro not https://docs.dpo2u.com/docs/intro
• Link to the most specific section when possible

Lists

• Use bulleted lists for unordered items (features, options)
• Use numbered lists only for sequential steps
• Start each item with a capital letter
• No trailing punctuation for single-phrase items; use periods for full sentences

Admonitions

Use Docusaurus admonitions to highlight important information. Each type has a specific purpose:

note

Use note for supplementary information that adds context but isn't essential to the current task. Example: "Compact contracts compile to a zero-knowledge circuit, not bytecode."

tip

Use tip for helpful suggestions, shortcuts, or best practices. Example: "Run the MCP server locally during development to avoid rate limits."

info

Use info for important context, links to related documentation, or ecosystem references. Example: "DPO2U builds on the Midnight Network, a partner chain of Cardano."

caution

Use caution for potential pitfalls, prerequisites that are easy to miss, or actions that could cause unexpected behavior. Example: "Ensure your Node.js version is 20 or higher before running the agent."

danger

Use danger sparingly — only for actions that could result in data loss, security vulnerabilities, or irreversible state changes. Example: "Never expose your agent's private key in client-side code."

Diagrams

Use Mermaid for all diagrams. Prefer graph LR (left-to-right) for data flows and graph TD (top-down) for hierarchies.

```mermaid
graph LR
    A[Input] --> B[Processing]
    B --> C[Output]
```

Guidelines:

• Keep diagrams simple — 3 to 8 nodes maximum
• Use descriptive labels inside brackets
• Add a text walkthrough below the diagram for accessibility
• Test both light and dark theme rendering

Page structure template

Every documentation page should follow this structure:

---
sidebar_position: N
---

# Page Title

One-paragraph introduction explaining what this page covers and who it's for.

:::info
Optional context admonition (ecosystem link, prerequisite, etc.)
:::

## First major section

Content here.

## Second major section

Content here.

## What's next

- [Related page 1](/docs/page-1)
- [Related page 2](/docs/page-2)

Writing checklist

Before submitting documentation changes, verify:

• Active voice used throughout
• All Midnight terminology matches the terminology table
• Code blocks have language specified
• Admonitions are used correctly (not overused)
• Internal links are relative paths
• Diagrams render in both light and dark mode
• Page follows the structure template
• No broken links (npm run build passes)