61 lines
1.6 KiB
Markdown
61 lines
1.6 KiB
Markdown
# 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/
|