search

YACS-RCOS / docs

Welcome to Yacs. We're happy to see you ❤️
https://yacs-rcos.github.io/
MIT License
2 stars 7 forks source link

Improve readability of some documents #13

Open kburk1997 opened 6 years ago

kburk1997 commented 6 years ago

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!

kburk1997 commented 6 years ago

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.

Bad-Science commented 6 years ago

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.