# MDN Technical Writing Reference

**Source:** [Creating effective technical documentation](https://developer.mozilla.org/en-US/blog/technical-writing/)  
**Author:** Dipika Bhattacharya, MDN Blog  
**Published:** 2024-02-13  
**Reviewed For:** Documentation Site IA Rebuild, 2026-06-29

## Why This Matters For MARS

The MARS documentation site should help readers act with confidence. This MDN
article is a reference for keeping public docs clear, concise, consistent,
well-structured, accessible, and easy to self-review.

## Principles To Apply

- Write for the actual reader and explain who needs to act.
- Introduce new terms before relying on them.
- Keep one idea per sentence or paragraph where possible.
- Use consistent terminology and casing.
- Organize docs around a clear goal and logical reader progression.
- Add examples or realistic use cases when a concept could feel abstract.
- Split long sections into digestible parts.
- Use descriptive link text that makes sense out of context.
- Proofread for flow, redundancy, tone, tense, and formatting.

## MARS Documentation Implications

- Public docs should start with the reader action before command detail.
- Homepage content should route readers, not carry every catalog entry.
- Security and governance claims should use precise language and avoid
  absolutes.
- Canonical links should say where they lead, not use vague "click here"
  phrasing.
- The documentation map should make source-of-truth status explicit.