gabrielmoreira Creating Documentation
Overview
This skill provides capabilities for creating and reviewing README files and other repository documentation that follows established best practices for structure, accessibility, and user experience.
Good documentation is the front door to your project. It helps users understand what your project does, how to use it, and how to contribute. This skill ensures documentation is clear, accessible, and follows industry standards.
Capabilities
| Capability | Action | Description |
|---|---|---|
| Create README | actions/create-readme.md |
Generate a comprehensive README for a repository |
| Create CONTRIBUTING | actions/create-contributing.md |
Generate contribution guidelines |
| Review | actions/review-documentation.md |
Analyse existing documentation for quality and accessibility |
Standards
This skill bundles the following standards in standards/:
| Standard | File | Description |
|---|---|---|
| README Structure | readme-structure.md |
Essential sections and organization for README files |
| Accessibility | accessibility.md |
Accessibility requirements for inclusive documentation |
| Writing Style | writing-style.md |
Plain language and readability guidelines |
| Markdown | markdown.md |
Markdown formatting best practices |
| Checklist | checklist.md |
Consolidated compliance and quality checklist |
Principles
1. Audience First
Write for your audience. A README's primary purpose is to help visitors quickly understand your project and get started. Don't assume prior knowledge—provide context and links for unfamiliar concepts.
2. Progressive Disclosure
Present information in order of importance:
- Title & Description: What is this project? (immediate)
- Installation & Usage: How do I use it? (primary)
- Contributing & License: How can I help? (secondary)
3. Accessibility Matters
Documentation should be accessible to all users:
- Use proper heading hierarchy (don't skip levels)
- Provide alt text for all images
- Write descriptive link text (not "click here")
- Use plain language and short sentences
4. Keep It Current
Outdated documentation is worse than no documentation. Include only information that can be maintained. Use automation where possible.
Usage
- Load this skill manifest
- Identify the required capability (create or review)
- Load the bundled standards from
standards/ - Execute the action following
actions/<capability>.md