[Wikimedia-l] making tech journalism easier to read

[Quim Gil]

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