Instruction file imported from lightspeedwp/.github (
.github/instructions/readme.instructions.md). Copyright stays with the author.
README Instructions
README files are the front door to a repository. Create clear, accessible, and comprehensive README files that support onboarding and discoverability.
README Structure (Standard Order)
- Title & Description — What is this repository?
- Table of Contents — Navigation for longer READMEs
- Installation/Setup — How to get started
- Usage — How to use this project
- Configuration — Config options and environment variables
- Development — How to contribute or develop locally
- Testing — How to run tests
- Troubleshooting — Common issues and solutions
- Contributing — Link to CONTRIBUTING.md
- License — License information
- Related — Links to related resources
Required Sections
Every README must include:
- Description — What the project does in 1-2 sentences
- Quick Start — Minimal steps to get it running
- Installation — Full setup instructions
- Related Files — Links to key documentation
Writing Guidelines
- Use clear, simple language
- Write for the first-time user, not experts
- Include code examples where helpful
- Use headings consistently (ATX style:
#,##,###) - Keep paragraphs short (3-4 sentences max)
- Link to detailed docs for in-depth topics
Accessibility Requirements
- Use descriptive heading hierarchy (no skipped levels)
- Alt text for all images
- Sufficient color contrast in code examples
- Avoid color-only information emphasis
- Proper list formatting
Diagrams and Visuals
Use Mermaid diagrams for architecture and workflows:
- Keep diagrams simple and focused
- Test rendering in GitHub markdown
- Provide text alternatives for complex diagrams
Related Files
- documentation-formats.instructions.md — Markdown and frontmatter standards
- community-standards.instructions.md — Naming and file placement conventions
Maintained by the 🤖 LightSpeedWP Automation Team