On 05/20/2013 08:45 PM, Sumana Harihareswara wrote:
When you're trying to write a blog.wikimedia.org entry or
wikitech-ambassadors email about a technical topic, but you want to make
sure nontechnical Wikimedians can read it, is there an automated check
you can run through?
For general readability we have http://www.readability-score.com/
But all those indexes have nothing to do with technical or non-technical
content or readers. They will tell long sentences with long words are
bad, short sentences with short words are good - tech aspects aside.
"Americans consume significant quantities of chocolate"
REALLY BAD!
Flesch-Kincaid Reading Ease -39
Grade Levels
Flesch-Kincaid Grade Level 20.2
Gunning-Fog Score 22.4
Coleman-Liau Index 31.3
SMOG Index 11.6
Automated Readability Index 19.3
Average Grade Level 21.0
"Set up git and fork the master repo"
VERY GOOD!
Flesch-Kincaid Reading Ease 93
Grade Levels
Flesch-Kincaid Grade Level 2.3
Gunning-Fog Score 3.2
Coleman-Liau Index 4.8
SMOG Index 1.8
Automated Readability Index -0.9
Average Grade Level 2.2
Aside from general readability, I also want to be careful about using
jargon, and substitute more accessible terminology where possible. I may
whip up a script to check whether some text has words from
https://meta.wikimedia.org/wiki/Glossary and the other site glossaries
in it, unless someone has a better idea.
"The master branch of the git repository" is clearly non suitable for
the beginning of an article, but there is nothing wrong in writing
exactly that deeper in the text, at the right time and in the right
context for the right audience.
Not all readers must/will read all articles entirely. You don't want to
throw casual readers into complex text, but you don't want to deceive
more specialist readers with generic words when precise terms exist and
that audience is familiar with them.
Good journalism is mostly about a lead paragraph for the masses followed
by an increasingly dense body text (aka the 5 Ws and the inverted
pyramid). You can adapt and change these rules at will, as long as you
are aware of them.
Paying more editorial attention to the title and the lead will allow
more room for complex terminology down in the body text. And this
applies to technical posts just as much as to other posts about other
expert fields for librarians, translators, lawyers, educators...
https://en.wikipedia.org/wiki/5_Ws
https://en.wikipedia.org/wiki/Inverted_pyramid
--
Quim Gil
Technical Contributor Coordinator @ Wikimedia Foundation
http://www.mediawiki.org/wiki/User:Qgil
_______________________________________________
Wikimedia-l mailing list
[email protected]
Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
