Documentation Style Guide

This guide defines standards for all documentation generated in the project.

Formatting

• Ensure there are no spelling errors. Avoid emojis and decorative Unicode characters (such as →, •, ★, ✓, 🎯, ✅).
• Avoid hyphens or dashes as separators between concepts. Instead of "concept A - concept B", rewrite the sentence.
• Prefer lists and tables over long paragraphs.
• Keep documents concise: specs and ADRs should be 1-2 pages, not novels.
• Never use #<number> in free text (e.g., "#1 priority", "#3 option"). Azure DevOps automatically converts #<number> into a work item link. Use "first", "third option", or rephrase the sentence.

Language

• Avoid promotional or exaggerated language.
• Do not use contrastive constructions:
  • "it's not just X, it's Y"
  • "it's not just about..."
  • "more than just..."
  • "goes beyond..."
• Describe directly what something is, without negating or minimizing alternatives.
• Use active voice and direct sentences.
• Avoid generic framing: if the sentence works in any project without modification, it is not saying anything useful.