doc-quality

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

1. Clarity: Can someone new to the topic understand this?
2. Accuracy: Are all technical details correct?
3. Completeness: Are there gaps that would confuse readers?
4. Tone: Does it match Replit's brand voice?
5. 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:

1. Point out specific issues with line references
2. Suggest concrete improvements (not just "make it better")
3. Provide rewritten examples when helpful
4. Balance criticism with recognition of what works well