- Be concise - Get to the point quickly
- Use headings - Break up content for easy scanning
- Active voice - "Configure the settings" not "Settings should be configured"
- Present tense - "The command shows..." not "The command will show..."
- Lead with important info - Don't bury key points
- Use progressive disclosure - Overview first, then details
- Group related content - Keep topics together
- End with actions - What should the reader do next?
- Use tables for structured data
- Use admonitions sparingly (too many = ignored)
- Use bullets for 3+ related items
- Use numbers for sequential steps
¶ Maintenance
- Review pages regularly
- Update outdated information
- Check that links still work
- Keep "last updated" meaningful
Don't:
- Write walls of text without headings
- Leave placeholder content
- Forget to add description and tags
- Create orphan pages with no links
Do:
- Preview before saving
- Link to related pages
- Use consistent terminology
- Ask for review on major changes