Code Readability Standards
Quick Reference
What & Why
Definition
>= 70% of modules have README with setup, usage, and architecture notes. Code review checks readability.
Business Value
Prevents 95% of direct-to-main commits and catches code quality issues 3-5 days earlier through automated PR reviews and branch protection Achieving >= 70% modules have comprehensive README is a key milestone toward this goal.
Context
This capability is part of the Foundation milestone's focus on establish baseline practices (testable, releasable, monitorable). Essential for teams targeting LT, CFR improvements.
Success Criteria
Target
>= 70% modules have comprehensive README
Measurement
Repository scanner for README existence and completeness
Evidence
- README template
- Sample READMEs
- Inner-source contribution guide
In Practice
Real-World Implementation
Teams use README template covering: purpose, setup instructions, API examples, architecture diagram, contribution guide.
Concrete Example
Implementation Guide
Implementation Steps
Follow the measurement approach: Repository scanner for README existence and completeness
For detailed step-by-step guidance, refer to the Code Quality & Review Standards Implementation Kit.
Resources
Implementation Kit
Code Quality & Review Standards KitTemplates
Browse all templatesRelated Resources
View learning pathsRelated Capabilities
Enables
What this unlocks
Complementary
Often adopted together, from the Code Quality & Review Standards epic
Troubleshooting & FAQs
Common Issues
Issue: Target metric not improving
Solution: Verify measurement is accurate, check if prerequisites are fully implemented, review evidence artifacts for completeness
Issue: Team resistance to adoption
Solution: Start with pilot team, demonstrate value with metrics, provide training and support during transition
Issue: Inconsistent implementation across teams
Solution: Create shared templates and guidelines, establish regular sync meetings, use automation to enforce standards
Frequently Asked Questions
Can we implement this before completing prerequisites?
While possible, it's not recommended. Prerequisites ensure foundational practices are in place, making this capability more effective and easier to adopt.
How long does implementation typically take?
Most capabilities can be implemented within 90 days when tackled as part of the Foundation milestone. Individual timelines vary based on team size and existing practices.