Style Guide

This style guide establishes the writing standards for DPO2U documentation.

Its main job is to keep the docs:

• clear
• technically honest
• useful to integrators
• resistant to drift between product copy and runtime reality

Voice and tone

Principles

Principle	Do	Don't
Active voice	"The agent validates the result."	"The result is validated by the agent."
Second person	"You can inspect the MCP runtime…"	"The user may inspect the MCP runtime…"
Present tense	"The runtime exposes capability discovery."	"The runtime will expose capability discovery."
Direct	"Run npm run build."	"You may want to consider building the docs."
Precise	"This backend is environment-dependent."	"This works everywhere."
Conservative	"The MCP runtime is the clearest public surface today."	"Everything is production-ready."

Audience

Write for developers, technical architects, and operator-minded evaluators who are integrating or assessing DPO2U.

Assume familiarity with:

• APIs
• command-line tools
• system architecture
• compliance and privacy vocabulary at a technical level

Do not assume familiarity with DPO2U-specific terminology. Define project-specific terms on first use.

Documentation posture

This is the most important editorial rule in the project:

prefer runtime truth over static marketing copy.

When there is any chance of drift, the docs should point readers to the live capability surface rather than freeze a claim that will age badly.

Write in layers

Separate these ideas clearly:

Layer	What it means
Current public runtime	what is publicly reachable and verifiable now
Environment-dependent backend	works in some local, private, or constrained path
Conceptual architecture	explains how the system is designed
Research / roadmap	direction, thesis, or partially hardened future work

Never collapse those layers into one story.

Terminology

Use the following terms consistently:

Term	Usage	Notes
MCP	Model Context Protocol	Expand on first use per page
Runtime truth	the most reliable currently reachable source of capability truth	Usually the live public MCP runtime
Live Mode	UI state backed by the current canonical runtime path	Distinct from demo or degraded
Degraded Mode	UI state using real but partial, delayed, or reduced backend data	Must be labeled honestly
Demo Mode	UI state used to explain workflow without pretending to be canonical live telemetry	Never disguise as live
Attestation	a verification-oriented result or artifact	Avoid implying on-chain settlement unless verified in context
Evidence reference	hash, CID, ID, or pointer to off-public-surface material	Prefer this over vague "proof link" wording
Verification backend	service or backend path used to validate, attest, or settle a result	Can be public, local, or environment-dependent
DID	Decentralized Identifier	Define when relevant, but do not force it into every page
LGPD	Lei Geral de Proteção de Dados	Brazilian data protection law
GDPR	General Data Protection Regulation	EU data protection law

Terms that require extra care

Use chain-, token-, or proving-system-specific terms only when they are necessary for the page.

If used, they must be clearly framed as one of:

• current validated path
• environment-dependent backend
• conceptual reference
• roadmap or research

Do not use specialized infrastructure terms as decorative branding.

Formatting standards

Headings

• Use sentence case for headings
• Use H2 (##) for major sections and H3 (###) for subsections
• Do not skip heading levels
• Keep headings concise

Code blocks

Always specify the language:

```typescript
const result = await fetchRuntimeCapability();
```

Use inline code for:

• file names
• function names
• commands
• variables
• endpoints
• paths

Links and cross-references

• Use descriptive link text
• Use relative paths for internal links
• Link to the most specific relevant page when possible
• Prefer links to canonical pages over repeating stale claims inline

Lists

• Use bullet lists for unordered items
• Use numbered lists only for sequence
• Start each item with a capital letter
• Use periods only when items are full sentences

Admonitions

Use Docusaurus admonitions deliberately.

note

Use note for supporting context that improves understanding but is not critical.

tip

Use tip for practical shortcuts, verification habits, or implementation best practices.

info

Use info for important context such as trust boundaries, capability-discovery pointers, or related docs.

caution

Use caution when the reader may confuse conceptual design with current runtime reality.

danger

Use danger only for irreversible, security-sensitive, or data-destructive situations.

Diagrams

Use Mermaid for diagrams.

Prefer:

• graph LR for flows
• graph TD for hierarchies

Guidelines:

• Keep diagrams simple
• Use descriptive labels
• Add explanatory text below when needed
• Avoid diagrams that imply a backend is live unless the page explicitly verifies that status

Page structure template

A good DPO2U documentation page usually follows this structure:

---
sidebar_position: N
---

# Page title

Short introduction explaining what the page covers and how it should be read.

## Current posture / scope

Explain whether the page is describing runtime truth, conceptual architecture, or research.

## Main sections

Content here.

## What's next

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

Writing checklist

Before submitting documentation changes, verify:

• The page distinguishes runtime truth from roadmap or concept
• Claims are not stronger than the evidence behind them
• Static counts are avoided when live discovery is the better source
• Code blocks have a language specified
• Internal links are relative
• Diagrams do not overclaim backend reality
• npm run build passes