[Wikimedia-l] making tech journalism easier to read

[Balázs Viczián]

uh... tech speak in general is usually like Marsian to me, even if it is in
my own language... might worth to put an effort into translating from geek
to human (like "obvious" things that are really not so obvious for the
masses) as well if you wish to improve readability :)

Balazs


2013/5/21 Quim Gil <qgil at wikimedia.org>

> 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/<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<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/5_Ws>
> https://en.wikipedia.org/wiki/**Inverted_pyramid<https://en.wikipedia.org/wiki/Inverted_pyramid>
>
> --
> Quim Gil
> Technical Contributor Coordinator @ Wikimedia Foundation
> http://www.mediawiki.org/wiki/**User:Qgil<http://www.mediawiki.org/wiki/User:Qgil>
>
>
> ______________________________**_________________
> Wikimedia-l mailing list
> Wikimedia-l at lists.wikimedia.**org <Wikimedia-l at lists.wikimedia.org>
> Unsubscribe: https://lists.wikimedia.org/**mailman/listinfo/wikimedia-l<https://lists.wikimedia.org/mailman/listinfo/wikimedia-l>
>