Improve readability of some documents
Opened this issue · 2 comments
I did a readability check of our current documentation as part of the accessibility audit.
As a general guideline, most text should aim for approximately an 8th grade reading level or lower. If that is not possible (e.g. highly technical or academic texts), provide a TL;DR in plain English that is an 8th grade reading level or lower.
The following pages need improvement with regards to readability:
| Page | Grade Level | Flesch Reading Ease | Gunning Fog Index |
|---|---|---|---|
| Repository Map | 9th grade | 54 (fairly difficult to read) | 11.7 (hard to read) |
| Code of Conduct (foreword only) | College | 37.6 (difficult to read) | 16.2 (difficult to read) |
| Running Yacs (for development) | 9th grade | 59.8 (standard/average) | 11.6 (hard to read) |
All other pages so far are at an 8th grade level or below!
If we can't get some texts below 9th grade reading level, we could add links to technologies used (e.g. rails, kafka) for those who are unfamiliar with those terms. In addition, we could add lists, tables, pictures, etc. to ease reading comprehension
However, a college reading level is very concerning and should be addressed ASAP.
I've rewritten most of this to reflect the new structure. I think it should help out but running yacs will probably still be high.