Documentation Standards

Technical documentation must be factually accurate, conservative in claims, and free of marketing language.

Formatting Rules

No emojis. No checkmarks, party poppers, or unicode decorations. Use plain text: "Compliant", "Implemented", "Supported", "Pending".

No excessive formatting. Use bold sparingly for genuine emphasis only.

Prohibited Language

Marketing Hyperbole - Never Use

• "Production-ready"
• "Enterprise-grade"
• "Best-in-class"
• "Industry-leading"
• "State-of-the-art"
• "Cutting-edge"
• "Revolutionary"
• "World-class"
• "Unparalleled"
• "Seamless"
• "Robust" (without specific meaning)
• "Powerful" (without quantification)

Absolute Claims - Never Use

• "Perfect"
• "Flawless"
• "100% accurate"
• "Guaranteed"
• "Always works"
• "Never fails"
• "Completely secure"

Competitive Claims - Never Use

• "Better than X"
• "Superior to alternatives"
• "More accurate than other tools"
• "Faster than existing solutions"

Vague Endorsement - Never Use

• "NASA-approved" (unless actually approved)
• "Certified accurate"
• "Validated by experts"
• "Industry-standard"

Required Patterns

Evidence-Backed Statements

Bounded Statements

Honest Limitations

Always include a limitations section stating what the software does NOT do.

Specific Methodology

When describing validation: state comparison target, methodology, dataset, and link to reproducible tests.

Commit Messages

No emojis. Use conventional commits format:

feat: add depth controller PID implementation
fix: resolve sleep_us variable shadowing
docs: update validation methodology section
test: add unit tests for state machine transitions

Do not editorialize. No "awesome", no exclamation points.

Code Comments

Comments explain WHY, not WHAT. No cheerleading.

// Bad
// This awesome function does the magic!

// Good  
// Apply temperature compensation per MS5837 datasheet section 4.2.

No TODO without ownership:

// Bad
// TODO: fix this later

// Good
// TODO(doug): Add timeout handling - see issue #47

README Structure

# Project Name

One-sentence factual description.

**Status:** Development / Testing / Stable
**Validation:** [Specific methodology and results]

## What This Does

[Factual description]

## Limitations

[Explicit statement of what it doesn't do]

## Validation

[Methodology, data sources, reproducible tests]

## Known Issues

[Current problems]

Pull Request Descriptions

State what changed and why. No self-congratulation.

## Add Core 1 health monitoring

Adds heartbeat-based detection of Core 1 stalls.

Changes:
- Add g_core1_heartbeat volatile counter
- Add check_core1_health() to safety monitor
- Add EVT_CORE1_STALL event code

Testing:
- Unit test: mock heartbeat stall, verify emergency trigger

Summary

Write as if reviewed by a skeptical engineer who will challenge every unsubstantiated claim.