Documentation clarity standards

Ensure documentation is clear, precise, and technically accurate to prevent confusion and build errors. This includes proper escaping of special characters, consistent terminology, version-specific accuracy, and unambiguous language.

copy reviewer prompt

Prompt

Reviewer Prompt
Deploy Agent

Ensure documentation is clear, precise, and technically accurate to prevent confusion and build errors. This includes proper escaping of special characters, consistent terminology, version-specific accuracy, and unambiguous language.

Key practices:

  • Escape HTML tags in markdown or wrap them in backticks to prevent parsing errors
  • Use consistent terminology throughout (e.g., “MDX v2” not “MDX 2”)
  • Provide version-specific information when features or paths change between releases
  • Choose precise words that reduce ambiguity (e.g., “unless specified” instead of “not specified”)
  • Add clarifying punctuation like quotes around file names when context could be confusing
  • Define technical terms when they might be unfamiliar to readers

Example of proper escaping:

<!-- Problematic -->
#### Handle <style> and <pre> tags in Handlebars/Glimmer

<!-- Better -->
#### Handle `<style>` and `<pre>` tags in Handlebars/Glimmer

Example of version-specific clarity:

<!-- Vague -->
- ES modules: `standalone.mjs`, starting in version 2.2

<!-- Clear -->
- ES modules: `standalone.mjs`, starting in version 3.0 (In version 2, `esm/standalone.mjs`.)

This prevents build failures, reduces reader confusion, and maintains professional documentation standards.

Source discussions