Writing Style
- Active Voice: Use "Configure the database" instead of "The database should be configured"
- Concise Language: Get straight to the point while remaining thorough
- Consistent Terminology: Use the same terms for the same concepts throughout all docs
- Audience-Focused: Write for the next team member who needs this information
- Action-Oriented: Use imperative mood for instructions ("Run the script" not "You should run the script")
Document Structure
- Start with Purpose: Begin each document with a clear statement of what it covers
- Logical Flow: Organize content from basic concepts to advanced topics
- Practical Examples: Include real code samples and real-world scenarios
- Progressive Disclosure: Start simple, add complexity gradually
- Troubleshooting: Add common issues and solutions where relevant
Quality Checklist
- Document has clear introduction stating its purpose
- All code examples are tested and functional
- Links are valid and up-to-date
- Screenshots are current and relevant (if used)
- Terminology matches other documentation
- No spelling or grammatical errors
- Instructions are complete and actionable