Documentation Improvement Template
Documentation Issue¶
Type of Documentation - [ ] User Guide - [ ] Developer Guide - [ ] API Documentation - [ ] Contributing Guidelines - [ ] README - [ ] Code Comments - [ ] Architecture Documentation - [ ] Setup Instructions - [ ] Other: ___________
Specific Document/Section Please specify which document or section needs improvement: - File path: [e.g., docs/user-guide/getting-started.md] - Section: [e.g., "Installation Instructions"] - Line numbers (if applicable): [e.g., lines 45-60]
Problem Description¶
What's Wrong? Clearly describe the issue with the current documentation: - [ ] Information is outdated - [ ] Information is incorrect - [ ] Information is missing - [ ] Information is unclear/confusing - [ ] Poor organization/structure - [ ] Broken links - [ ] Missing code examples - [ ] Inconsistent formatting - [ ] Accessibility issues - [ ] Other: ___________
Detailed Description Provide specific details about what needs to be improved.
Proposed Solution¶
Suggested Changes Describe what changes you think should be made:
Content Improvements - What information should be added? - What should be clarified or rewritten? - What examples would be helpful?
Structural Improvements - How should the content be reorganized? - What sections should be added or removed? - How can navigation be improved?
Target Audience¶
Who would benefit from this improvement? - [ ] New users - [ ] Experienced users - [ ] New developers - [ ] Experienced developers - [ ] Researchers - [ ] Contributors - [ ] All audiences
User Experience Impact How would this improvement help users?
Additional Context¶
Current Behavior What happens when users follow the current documentation?
Expected Behavior What should happen with improved documentation?
Related Documentation Are there other documents that should be updated consistently?
External References Any external resources that could help improve the documentation?
Implementation Details¶
Content Type - [ ] Text content - [ ] Code examples - [ ] Screenshots/Images - [ ] Diagrams - [ ] Videos - [ ] Interactive elements
Scope of Changes - [ ] Minor text edits - [ ] Section rewrite - [ ] New section/page - [ ] Structural reorganization - [ ] Multiple document updates
Technical Requirements - [ ] New screenshots needed - [ ] Code examples need testing - [ ] Links need verification - [ ] Diagrams need creation/update - [ ] Translation updates needed
Priority and Impact¶
Priority Level - [ ] Critical - Blocking users from completing tasks - [ ] High - Causing significant confusion - [ ] Medium - Noticeable improvement needed - [ ] Low - Minor enhancement
User Impact - [ ] Affects all users - [ ] Affects new users primarily - [ ] Affects developers primarily - [ ] Affects specific user group: ___________
Acceptance Criteria¶
Definition of Done - [ ] Content is accurate and up-to-date - [ ] Information is clear and well-organized - [ ] Code examples work correctly - [ ] Links are functional - [ ] Screenshots are current - [ ] Content follows style guide - [ ] Accessibility guidelines are met - [ ] Related documents are updated
Review Checklist - [ ] Technical accuracy verified - [ ] Content clarity confirmed - [ ] Examples tested - [ ] Links checked - [ ] Formatting consistent - [ ] Grammar and spelling correct
Volunteer Information¶
Can you help implement this improvement? - [ ] Yes, I can write the content - [ ] Yes, I can provide technical review - [ ] Yes, I can create screenshots/diagrams - [ ] Yes, I can test the documentation - [ ] No, but I can provide feedback - [ ] No, I'm just reporting the issue
Timeline If you're volunteering, when could you work on this?
Checklist before submitting: - [ ] I have searched for existing documentation issues - [ ] I have clearly identified the problem - [ ] I have provided specific suggestions - [ ] I have considered the target audience - [ ] I have checked related documentation