In short
- Definition: The ease with which code, documentation or user-facing text can be read and understood.
- Goal: Reduce misunderstanding and the time needed to learn and maintain the system.
- Example S.M.A.R.T. requirement: User-facing text at a Flesch reading-ease score above 60, and 100% of code passing the agreed style and complexity checks.
1. Definition
As a non-functional requirement, readability describes how easily text can be read and understood: user-facing content, documentation and the code itself [1], [2].
If users have to read it twice, they will call support instead.Key takeaway
For user content, readability depends on short sentences, common words, active voice, clear structure and good typography. Plain language guidance, such as the U.S. federal guidelines [3], says the first rule is to write for your audience. Formulas such as the Flesch reading-ease score give a rough, automatic measure [4].
For code, readability means clear names, small functions, consistent style and useful comments, so that others can understand and change it safely.
2. Goal
The goal is to reduce misunderstanding and the time needed to learn, use and maintain the system.
Unclear text causes user errors, support calls and legal disputes; unreadable code slows every change and hides bugs.
3. How to Measure It (S.M.A.R.T.)
| Metric | Unit | Typical target | How to measure |
|---|---|---|---|
| Reading-ease of user-facing text | Flesch reading-ease score | > 60 | Readability tool on content |
| Plain language review | % of key screens reviewed | 100% | Content review checklist |
| Code style compliance | % of files passing checks | 100% | Linter and formatter in CI |
| Code complexity | Cyclomatic complexity per function | ≤ 10 | Static analysis |
Reading-ease formulas only count sentence and word length. Use them as a signal, and confirm with tests by real readers.
4. Example Requirements
Each requirement below is ready to copy into a specification: specific, measurable, achievable, relevant and time-bound.
- User content: “User-facing help text and error messages shall reach a Flesch reading-ease score above 60 and be reviewed against the plain language checklist before release.”
- Code: “100% of code shall pass the agreed formatter and linter rules, and no function shall exceed a cyclomatic complexity of 10.”
- Legal text: “The privacy notice shall have a short summary that test users can explain correctly in their own words.”
5. Questions to Ask Stakeholders
- Who reads the text, and what is their level of expertise?
- In which languages must content be readable?
- Which texts are most critical (errors, legal, instructions)?
- Which coding standards apply?
- Who reviews content before release?
- How will readability be tested with real readers?
6. Common Pitfalls
- Jargon. Internal terms confuse users. Use words your audience uses.
- Relying only on scores. Formulas miss meaning and context. Test with readers.
- Clever code. Short tricks save lines but cost understanding.
7. Related NFRs
- Categories of Non-Functional Requirements — the full checklist of NFR categories.
- Usability — readable content makes interfaces easier to use.
- Accessibility — clear language is part of cognitive accessibility.
- Maintainability — readable code is faster to change.
- Documentation — documentation must be readable to be useful.
8. FAQ
A formula based on sentence length and syllables per word; higher scores mean easier text.
Writing that the intended audience can find, understand and use the first time they read it.
Indirectly, through style checks, complexity metrics and code review feedback.
9. Acronyms, Initialisms & Terms
Acronyms are abbreviations pronounced as words (like NASA); initialisms are spelled out letter by letter (like FBI). The classification below follows common pronunciation.
Acronyms
| Abbreviation | Stands for | Definition | Ref. |
|---|---|---|---|
| SMART | Specific, Measurable, Achievable, Relevant, Time-bound | Criteria for writing a goal or requirement so that anyone can check whether it has been met. | [5] |
Initialisms
| Abbreviation | Stands for | Definition | Ref. |
|---|---|---|---|
| CI | Continuous integration | Practice of merging code changes often, with each change checked automatically by builds and tests. | [6] |
| FAQ | Frequently asked questions | List of common questions with their answers. | [7] |
| NFR | Non-functional requirement | Requirement that describes how well a system must work (its qualities, such as speed or security) rather than what it does. | [2] |
Terms
Plain-language definitions of technical and project-management terms used in this article.
| Term | Plain-language definition | Ref. |
|---|---|---|
| Cyclomatic complexity | Measure of how many independent paths run through a piece of code; higher means harder to test. | [8] |
| Linter | Tool that automatically flags programming errors and style problems in code. | [9] |
| Stakeholder | Person or group with an interest in the system: users, sponsors, operators, regulators. | [10] |
| Static analysis | Automatic examination of code for errors without running it. | [11] |
10. Sources and Further Reading
- [1] “Readability.” Wikipedia. https://en.wikipedia.org/wiki/Readability (accessed Nov. 18, 2026).
- [2] “Non-functional requirement.” Wikipedia. https://en.wikipedia.org/wiki/Non-functional_requirement (accessed Nov. 18, 2026).
- [3] “Principles of plain language.” Digital.gov. https://digital.gov/guides/plain-language/principles (accessed Nov. 18, 2026).
- [4] “Flesch–Kincaid readability tests.” Wikipedia. https://en.wikipedia.org/wiki/Flesch–Kincaid_readability_tests (accessed Nov. 18, 2026).
- [5] “SMART criteria.” Wikipedia. https://en.wikipedia.org/wiki/SMART_criteria (accessed Nov. 19, 2026).
- [6] “Continuous integration.” Wikipedia. https://en.wikipedia.org/wiki/Continuous_integration (accessed Nov. 19, 2026).
- [7] “FAQ.” Wikipedia. https://en.wikipedia.org/wiki/FAQ (accessed Nov. 19, 2026).
- [8] “Cyclomatic complexity.” Wikipedia. https://en.wikipedia.org/wiki/Cyclomatic_complexity (accessed Nov. 19, 2026).
- [9] “Lint (software).” Wikipedia. https://en.wikipedia.org/wiki/Lint_(software) (accessed Nov. 19, 2026).
- [10] “Project stakeholder.” Wikipedia. https://en.wikipedia.org/wiki/Project_stakeholder (accessed Nov. 19, 2026).
- [11] “Static program analysis.” Wikipedia. https://en.wikipedia.org/wiki/Static_program_analysis (accessed Nov. 19, 2026).
Written by Philippe Huard · LinkedIn · Last updated: November 18, 2026 · Header photo by @kellysikkema; inline photo by @brett_jordan, both on Unsplash.








