Instruction File Name

writing-style.instructions.md

Scope

Workspace-level (applies to entire repository)

Purpose

Establish consistent voice, tone, and language conventions for all markdown content in the repository.

As documentation grows, contributors currently rely on implicit patterns observed in existing docs—which works but doesn't scale for new contributors or cross-team collaboration. A formal writing style guide will:

• Set clear expectations for documentation voice and tone
• Reduce review friction by providing objective style criteria
• Help AI assistants (Copilot, etc.) generate content matching our conventions
• Preserve the adaptable, professional-yet-accessible tone already present in our best docs

Requirements

• Voice and Tone: Define formal vs. instructional context guidance
• Language and Vocabulary: Precision, variety, jargon handling conventions
• Sentence Structure: Length variation and clarity principles
• Structural Patterns: Heading organization and transitions
• Pronoun Usage: Context-appropriate selection ("we", "you", "I", impersonal)
• Clarity Principles: Front-loading information, using examples, avoiding buried ledes
• Adaptability: Register shifting by document type (strategic → technical → casual)
• applyTo: Target **/*.md for all markdown files