BMAD-METHOD/expansion-packs/bmad-technical-writing/data/technical-writing-standards.md

Technical Writing Standards

Note: This is a Sprint 1 placeholder. Full technical writing standards will be added in Sprint 2.

Current Guidance

Basic writing principles are embedded in:

• Agent personas (emphasis on clarity, consistency)
• Task workflows (quality checkpoints)
• Checklists (validation criteria)

Sprint 2 Additions

Full standards will include:

• Clarity principles (from research section 11x)
• Consistency requirements (from research section 11y)
• Accessibility guidelines (from research section 11z)
• Structure best practices (from research section 11za)
• Voice and tone guidelines
• Formatting conventions
• Cross-reference standards
• Glossary and index creation

Key Principles (Interim Guidance)

Clarity

• Use simple, direct language
• Explain technical terms on first use
• Provide examples for abstract concepts
• Break complex ideas into steps

Consistency

• Use terminology consistently
• Follow established patterns
• Maintain uniform formatting
• Apply style guide uniformly

Accessibility

• Consider diverse reader backgrounds
• Provide multiple explanations when helpful
• Use inclusive language
• Ensure code examples work universally

Structure

• Logical progression of topics
• Clear section headings
• Predictable chapter patterns
• Strong transitions between sections

Resources

• Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
• Google Developer Documentation Style Guide: https://developers.google.com/style
• Write the Docs: https://www.writethedocs.org/guide/writing/style-guides/