tomevault-io Documentation Quality Review Skill
This skill helps you review and improve documentation using proven best practices.
Quick Quality Checklist
When reviewing documentation, check:
✅ Easy to Skim
- Content split into sections with clear titles
- Informative titles (not abstract nouns like "Results")
- Short paragraphs (1-3 sentences ideal)
- Topic sentences start paragraphs
- Important takeaways up front
- Bullets and tables used frequently
- Important text bolded
✅ Well Written
- Simple sentences (under 25 words)
- Active voice throughout
- No ambiguous phrasing
- Consistent terminology
- Demonstrative pronouns avoided ("this" → specific term)
✅ Broadly Helpful
- Simple language (non-native speakers can understand)
- No unexplained abbreviations
- Solutions to potential problems included
- Specific, accurate terminology
- Code examples are general and exportable
- No bad habits demonstrated
Review Focus Areas
- Clarity: Can someone new to the topic understand this?
- Accuracy: Are all technical details correct?
- Completeness: Are there gaps that would confuse readers?
- Tone: Does it match Replit's brand voice?
- Links: Are all references valid and helpful?
Common Issues to Fix
- Long paragraphs → Split into shorter chunks
- Passive voice → Convert to active voice
- "Click here" links → Use descriptive link text
- Missing context → Add brief explanations
- Jargon → Replace with simpler terms or define first use
- Buried information → Move important points to the top
For Complete Guidelines
Read GOOD_DOCS.md for:
- Complete documentation best practices
- Detailed writing guidelines
- Examples of good vs bad documentation
- Specific techniques for improvement
Providing Feedback
When reviewing:
- Point out specific issues with line references
- Suggest concrete improvements (not just "make it better")
- Provide rewritten examples when helpful
- Balance criticism with recognition of what works well
Converted and distributed by TomeVault — claim your Tome and manage your conversions.