Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve readability of some documents #13

Open
kburk1997 opened this issue Sep 18, 2018 · 2 comments
Open

Improve readability of some documents #13

kburk1997 opened this issue Sep 18, 2018 · 2 comments

Comments

@kburk1997
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants