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/ to check, for example, the Flesch-Kincaid reading ease. My blog entry https://blog.wikimedia.org/2013/02/05/how-the-technical-operations-team-stop... has a grade level of 11.5, meaning that it would be difficult for someone to read it unless they had about as much English fluency as an average US student in their last year of pre-college schooling. In the future I will probably aim more for a grade level of 10 or so; we have a lot of non-native English speakers in our community. I think it's too difficult to rewrite everything in Up-Goer 5 http://splasho.com/upgoer5/ or Simple English Wikipedia style, even for regular-person-friendly blog entries about WMF Engineering,[0] but I am willing to be told if I am wrong.
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.
On 5/21/13 5:45 AM, 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?
<I can not help making that comment given the topic of your email, sorry>
I read this sentence at least 4 times, trying to figure out what you meant.
At first sight, I thought some words were missing (when... but... >>> usually, a "when" is followed by a "then" not by a "but").
Then I realized that the "but" part was to be read as an additional comment and that what matters was actually "when" followed by a question. I then thought "is that a question to us" ? At second sight, it actually looks to be a question to us. I started thinking "what is meant by automated check" ???
I thought the next paragraph would bring some light on what you meant by "automated check" so that it would become possible to answer your question (just wanted to help...)
Last, I realize that the question was actually meant from you, to us. But was supposed to be a point we were actually wondering about. And that your email was actually an answer to this prospective question (in case we might wonder). The question was not a question.
Actually the rest of the explanation uses only one expression that are unknown to me ("whip up a script") but I am happy to say I understood the general meaning. Still, I would suggest avoid weird sentences such as "when... but... is there ?". Be straight to the point.
For information, the grade of your email is : Average Grade Level 8.7 (yeah !) Which is good on the paper (sort of paper). But still was hard to understand. I am still not quite sure what the goal of your email exactly was :(
But I loved the link to http://www.readability-score.com/ :)
Flo
My own grade is 5.9...
For general readability we have http://www.readability-score.com/ to check, for example, the Flesch-Kincaid reading ease. My blog entry https://blog.wikimedia.org/2013/02/05/how-the-technical-operations-team-stop... has a grade level of 11.5, meaning that it would be difficult for someone to read it unless they had about as much English fluency as an average US student in their last year of pre-college schooling. In the future I will probably aim more for a grade level of 10 or so; we have a lot of non-native English speakers in our community. I think it's too difficult to rewrite everything in Up-Goer 5 http://splasho.com/upgoer5/ or Simple English Wikipedia style, even for regular-person-friendly blog entries about WMF Engineering,[0] but I am willing to be told if I am wrong.
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.
Slightly off-topic, but I would recommend using the SMOG Index rather than FKT - there's some academic work done that indicates FKT actually /underestimates/ the reading difficulty of a sentence. And, of course, it is difficult for the results to be transparent to people outside the United States.
On 21 May 2013 09:47, Florence Devouard anthere9@yahoo.com wrote:
On 5/21/13 5:45 AM, 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?
<I can not help making that comment given the topic of your email, sorry>
I read this sentence at least 4 times, trying to figure out what you meant.
At first sight, I thought some words were missing (when... but... >>> usually, a "when" is followed by a "then" not by a "but").
Then I realized that the "but" part was to be read as an additional comment and that what matters was actually "when" followed by a question. I then thought "is that a question to us" ? At second sight, it actually looks to be a question to us. I started thinking "what is meant by automated check" ???
I thought the next paragraph would bring some light on what you meant by "automated check" so that it would become possible to answer your question (just wanted to help...)
Last, I realize that the question was actually meant from you, to us. But was supposed to be a point we were actually wondering about. And that your email was actually an answer to this prospective question (in case we might wonder). The question was not a question.
Actually the rest of the explanation uses only one expression that are unknown to me ("whip up a script") but I am happy to say I understood the general meaning. Still, I would suggest avoid weird sentences such as "when... but... is there ?". Be straight to the point.
For information, the grade of your email is : Average Grade Level 8.7 (yeah !) Which is good on the paper (sort of paper). But still was hard to understand. I am still not quite sure what the goal of your email exactly was :(
But I loved the link to http://www.readability-score.**com/http://www.readability-score.com/:)
Flo
My own grade is 5.9...
For general readability we have http://www.readability-score.**com/http://www.readability-score.com/to
check, for example, the Flesch-Kincaid reading ease. My blog entry https://blog.wikimedia.org/**2013/02/05/how-the-technical-** operations-team-stops-**problems-in-their-tracks/https://blog.wikimedia.org/2013/02/05/how-the-technical-operations-team-stops-problems-in-their-tracks/ has a grade level of 11.5, meaning that it would be difficult for someone to read it unless they had about as much English fluency as an average US student in their last year of pre-college schooling. In the future I will probably aim more for a grade level of 10 or so; we have a lot of non-native English speakers in our community. I think it's too difficult to rewrite everything in Up-Goer 5 http://splasho.com/upgoer5/ or Simple English Wikipedia style, even for regular-person-friendly blog entries about WMF Engineering,[0] but I am willing to be told if I am wrong.
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/Glossaryhttps://meta.wikimedia.org/wiki/Glossaryand the other site glossaries in it, unless someone has a better idea.
______________________________**_________________ Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.**org Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/**mailman/listinfo/wikimedia-lhttps://lists.wikimedia.org/mailman/listinfo/wikimedia-l
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
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@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/Glossaryhttps://meta.wikimedia.org/wiki/Glossaryand 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_pyramidhttps://en.wikipedia.org/wiki/Inverted_pyramid
-- Quim Gil Technical Contributor Coordinator @ Wikimedia Foundation http://www.mediawiki.org/wiki/**User:Qgilhttp://www.mediawiki.org/wiki/User:Qgil
______________________________**_________________ Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.**org Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/**mailman/listinfo/wikimedia-lhttps://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Quim Gil, 21/05/2013 23:15:
[...] 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
I agree that this is more useful, with the caveats by Lodewijk. As for our English texts, aside from jargon, their main deficiency is IMHO usually in not considering language diversity. The issue is very apparent in our requests for translations: often, you have very "simple" and short sentences which are translated in a way that reverses their meaning upside down. An article or pronoun implicit in English, if misunderstood by a native speaker of a language where the article or pronoun matters, is enough to spoil an entire text. What to do? 1) Some time ago I added some short leaflets here, but more and better resources are needed: http://meta.wikimedia.org/wiki/Writing_clearly#Advice_from_the_experts 2) An automatical service we'd benefit from is one which takes a text and highlights all idiomatic expressions (which may be obvious in USA English but mean the opposite in UK English or just nothing for most people), formal/literary expressions (which may mean nothing for most native speakers and at the same time be obvious for speakers of another language more closely related to them) etc. Let me also add that – personally – I have no problems reading and understanding sentences spanning multiple pages, if they were written by Proust (who always has a reason), but I have big problems understanding texts which lack coherency and focus. English texts composed by many scattered short sentences, without conjunctions and other sentence connectors, are for me very painful to read. However, it seems most people prefer to have many small concepts and to connect the dots themselves to get the figure as they can.
Nemo
Hi
My main suggestion (valid for all posts, technical or not) would be to start with a clearly identified cap as summary. And put an extra effort so that this cap is written in simple and straightforward message.
In that regards, this post is pretty good generally http://blog.wikimedia.org/2013/05/20/flow-next-generation-discussion-system/
It gives a nice summary of the content of the post. It can be translated easily. It provides information. The cap summary at the top could be even better identified though.
On the other hand, this one http://blog.wikimedia.org/2013/04/08/intro-to-the-statistics-of-ab-testing-w... is quite "technical" in nature as well, but though very interesting, it fails to pass the "summary" state. The little paragraph at the top is not a summary of the post, but a text putting the post in context. I think this post would benefit from a two lines summary of the content of the post itself. Its design is 1) context, 2) development 3) conclusion.
One of the problems non English speakers face is that they are slower to identify the "important" points. Stumbling over difficult words and jargon is obviously not helping. A hard text will need to be read more than one time to just "get the idea"
In this situation, it is very helpful to rather write in the following way 1) summary of the entire post with context, arguments and quick conclusion 2) expanded context 3) expanding on argument a 4) expanding on argument b 5) expanding on argument c 6) full conclusion
1) should be short sentences, simple sentences and as little jargon as possible 2-6 can be more complex and detailed and links should be added to provided additional context and explanation of jargon.
The only drawback of this solution is that the author will feel frustrated if he wants to develop a story and use surprise/discovery effects. But there are many benefits to counter balance this loss.
Flo
PS: who will point out though that the tech posts on the wikimedia blog are actually quite good generally.
On 5/22/13 11:44 AM, Federico Leva (Nemo) wrote:
Quim Gil, 21/05/2013 23:15:
[...] 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
I agree that this is more useful, with the caveats by Lodewijk. As for our English texts, aside from jargon, their main deficiency is IMHO usually in not considering language diversity. The issue is very apparent in our requests for translations: often, you have very "simple" and short sentences which are translated in a way that reverses their meaning upside down. An article or pronoun implicit in English, if misunderstood by a native speaker of a language where the article or pronoun matters, is enough to spoil an entire text. What to do?
- Some time ago I added some short leaflets here, but more and better
resources are needed: http://meta.wikimedia.org/wiki/Writing_clearly#Advice_from_the_experts 2) An automatical service we'd benefit from is one which takes a text and highlights all idiomatic expressions (which may be obvious in USA English but mean the opposite in UK English or just nothing for most people), formal/literary expressions (which may mean nothing for most native speakers and at the same time be obvious for speakers of another language more closely related to them) etc. Let me also add that – personally – I have no problems reading and understanding sentences spanning multiple pages, if they were written by Proust (who always has a reason), but I have big problems understanding texts which lack coherency and focus. English texts composed by many scattered short sentences, without conjunctions and other sentence connectors, are for me very painful to read. However, it seems most people prefer to have many small concepts and to connect the dots themselves to get the figure as they can.
Nemo
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
On 05/22/2013 08:39 AM, Florence Devouard wrote:
My main suggestion (valid for all posts, technical or not) would be to start with a clearly identified cap as summary. And put an extra effort so that this cap is written in simple and straightforward message.
Yes! Don't assume readers will reach the end of your post. You will be lucky if they end the lead paragraph! This is the Who, What, When, Where, Why (and How) rule. Skip any of this if you wish, but do it consciously.
Looking at more examples of first paragraphs:
Getting ready for ULS everywhere https://blog.wikimedia.org/2013/05/22/getting-ready-for-uls-everywhere-2/ Pretty ok, although an extra sentence explaining what is Universal Language Selector would be welcome. Yes, it has been explained in several posts in the same blog but we can't simply assume that your readers today have also read those previous articles.
Request for proposals: MediaWiki release management https://blog.wikimedia.org/2013/05/21/request-for-proposals-mediawiki-releas... The actual lead paragraph is the 4th, and only re-sorting the paragraphs 4,5,1,2,3 would make the text a lot clearer. (I'm sitting literally next to Greg and Rob so I hope they don't get mad at me!)
Also related: "Request for proposals: MediaWiki release management" is not very clear as a headline for outsiders. I hesitated sharing the official tweet that came with this header. Erik put it this way: "The Wikimedia Foundation is looking for a partner to develop the third party MediaWiki open source ecosystem" and my retweet quickly followed.
We can probably add "The Microblogging Sharing Test" to our headlines. :)
No math or script will easily catch any of this, and this is why big media must keep paying plenty of humans to write good stories.
I would like to remind everyone that many blog posts are now drafted in public at https://meta.wikimedia.org/wiki/Wikimedia_Blog/Drafts . Pre-publication copyedits or comments on better structuring etc. are welcome there, so don't feel restricted to posting armchair advice on mailing lists ;) For example, the Flow post discussed below (I agree with Florence's points btw) was up at https://meta.wikimedia.org/wiki/Wikimedia_Blog/Drafts/Help_us_design_our_nex... before it was posted on the blog.
This is a great thread with a lot of good points, and of course in the blog team we already routinely use many of them when reviewing and editing posts, often pointing authors to https://meta.wikimedia.org/wiki/Wikimedia_Blog/Guidelines (e.g. "Try to use the Inverted pyramid structure, so that people get the heart of the story from the beginning. / Use a strong lead sentence/paragraph that explains the most salient and important point of your story up front.")
On Wed, May 22, 2013 at 8:39 AM, Florence Devouard anthere9@yahoo.com wrote:
Hi
My main suggestion (valid for all posts, technical or not) would be to start with a clearly identified cap as summary. And put an extra effort so that this cap is written in simple and straightforward message.
In that regards, this post is pretty good generally http://blog.wikimedia.org/2013/05/20/flow-next-generation-discussion-system/
It gives a nice summary of the content of the post. It can be translated easily. It provides information. The cap summary at the top could be even better identified though.
On the other hand, this one http://blog.wikimedia.org/2013/04/08/intro-to-the-statistics-of-ab-testing-w... is quite "technical" in nature as well, but though very interesting, it fails to pass the "summary" state. The little paragraph at the top is not a summary of the post, but a text putting the post in context. I think this post would benefit from a two lines summary of the content of the post itself. Its design is 1) context, 2) development 3) conclusion.
One of the problems non English speakers face is that they are slower to identify the "important" points. Stumbling over difficult words and jargon is obviously not helping. A hard text will need to be read more than one time to just "get the idea"
In this situation, it is very helpful to rather write in the following way
summary of the entire post with context, arguments and quick conclusion
expanded context
expanding on argument a
expanding on argument b
expanding on argument c
full conclusion
should be short sentences, simple sentences and as little jargon as
possible 2-6 can be more complex and detailed and links should be added to provided additional context and explanation of jargon.
The only drawback of this solution is that the author will feel frustrated if he wants to develop a story and use surprise/discovery effects. But there are many benefits to counter balance this loss.
Flo
PS: who will point out though that the tech posts on the wikimedia blog are actually quite good generally.
On 5/22/13 11:44 AM, Federico Leva (Nemo) wrote:
Quim Gil, 21/05/2013 23:15:
[...] 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
I agree that this is more useful, with the caveats by Lodewijk. As for our English texts, aside from jargon, their main deficiency is IMHO usually in not considering language diversity. The issue is very apparent in our requests for translations: often, you have very "simple" and short sentences which are translated in a way that reverses their meaning upside down. An article or pronoun implicit in English, if misunderstood by a native speaker of a language where the article or pronoun matters, is enough to spoil an entire text. What to do?
- Some time ago I added some short leaflets here, but more and better
resources are needed: http://meta.wikimedia.org/wiki/Writing_clearly#Advice_from_the_experts 2) An automatical service we'd benefit from is one which takes a text and highlights all idiomatic expressions (which may be obvious in USA English but mean the opposite in UK English or just nothing for most people), formal/literary expressions (which may mean nothing for most native speakers and at the same time be obvious for speakers of another language more closely related to them) etc. Let me also add that – personally – I have no problems reading and understanding sentences spanning multiple pages, if they were written by Proust (who always has a reason), but I have big problems understanding texts which lack coherency and focus. English texts composed by many scattered short sentences, without conjunctions and other sentence connectors, are for me very painful to read. However, it seems most people prefer to have many small concepts and to connect the dots themselves to get the figure as they can.
Nemo
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Hi Sumana,
I've found the advice from the Plain English Campaign pretty good - they have Drivel Defence (although I've not used it, so can't comment on it specifically):
http://www.plainenglish.co.uk/drivel-defence.html
Cheers, Kim Osman
On 21/05/13 1:45 PM, "Sumana Harihareswara" sumanah@wikimedia.org 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/ to check, for example, the Flesch-Kincaid reading ease. My blog entry https://blog.wikimedia.org/2013/02/05/how-the-technical-operations-team-st ops-problems-in-their-tracks/ has a grade level of 11.5, meaning that it would be difficult for someone to read it unless they had about as much English fluency as an average US student in their last year of pre-college schooling. In the future I will probably aim more for a grade level of 10 or so; we have a lot of non-native English speakers in our community. I think it's too difficult to rewrite everything in Up-Goer 5 http://splasho.com/upgoer5/ or Simple English Wikipedia style, even for regular-person-friendly blog entries about WMF Engineering,[0] but I am willing to be told if I am wrong.
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.
-- Sumana Harihareswara Engineering Community Manager Wikimedia Foundation
[0] I just tried rewriting a couple sentences from my blog post in Up-Goer 5 style. "Now, we are looking forward to making more places to give people their words and pictures, more quickly. The team is planning to make another place like that."
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
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?
I'd recommend doing what we do on the wiki to make topics easier or more accessible: include a lot of links. The blog is worryingly low on links in each post, given that it's the blog of Wikimedia, king of [[links]]. Perhaps linking needs to be made easier in WordPress?
I'm not sure there's much else to be said other than "avoid the use of (unexplained) jargon and write clearly and concisely."
The Wikimedia blog is made up of several sub-blogs. The tech blog seems like it would inherently be more... technical than the community blog or the fundraising blog. Unless the larger issue is the audience question. That's a bit of a rabbit hole, though.
MZMcBride
I think what is even more helpful to people, is to avoid abbreviations as much as possible, or explain them. For example: * Up-Goer 5 (but there was a link next to it - which allows you to guess what it means) * SMOG (the stuff that is in the air, right?) * FKT
Usually this kind of abbreviations (without in-text explanation) makes texts much harder to read. Even a link to an explanation is usually less helpful than a few words of what it actually is (especially when reading offline - yes, that world still exists).
Anyway, aside from that, I think Quim has a point that jargon is much more dangerous than complicated words. However, don't underestimate the amount of non-native volunteers. I have all too often heard at meetings that people felt insecure to participate in a discussion because they felt it was above their level. Some native speakers have the habit of going all wild with complicated words (this is not too common, gladly) and then you realize that texts with long sentences with lots of long complicated words are much harder to understand, even if you understand each word by itself.
So this score thing Sumana linked to might indeed be helpful, but probably only at longer texts. At short texts there is not enough critical mass to be precise.
Lodewijk
2013/5/22 MZMcBride z@mzmcbride.com
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?
I'd recommend doing what we do on the wiki to make topics easier or more accessible: include a lot of links. The blog is worryingly low on links in each post, given that it's the blog of Wikimedia, king of [[links]]. Perhaps linking needs to be made easier in WordPress?
I'm not sure there's much else to be said other than "avoid the use of (unexplained) jargon and write clearly and concisely."
The Wikimedia blog is made up of several sub-blogs. The tech blog seems like it would inherently be more... technical than the community blog or the fundraising blog. Unless the larger issue is the audience question. That's a bit of a rabbit hole, though.
MZMcBride
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
I agree with everyone here and would add that no matter how hard to read, *any blog entry at all* on this Tech stuff is highly welcome, because it also serves as a written record to refer back to in various ongoing technical projects. Any documentation at all is better than none. I find myself regularly reading old blog entries in order to get a feeling for the purpose of ongoing work. Once begun, people rarely talk about the *why* part of their project, just their progress and the *what*.
Keep up the good work, Sumana!
2013/5/22, Lodewijk lodewijk@effeietsanders.org:
I think what is even more helpful to people, is to avoid abbreviations as much as possible, or explain them. For example:
- Up-Goer 5 (but there was a link next to it - which allows you to guess
what it means)
- SMOG (the stuff that is in the air, right?)
- FKT
Usually this kind of abbreviations (without in-text explanation) makes texts much harder to read. Even a link to an explanation is usually less helpful than a few words of what it actually is (especially when reading offline - yes, that world still exists).
Anyway, aside from that, I think Quim has a point that jargon is much more dangerous than complicated words. However, don't underestimate the amount of non-native volunteers. I have all too often heard at meetings that people felt insecure to participate in a discussion because they felt it was above their level. Some native speakers have the habit of going all wild with complicated words (this is not too common, gladly) and then you realize that texts with long sentences with lots of long complicated words are much harder to understand, even if you understand each word by itself.
So this score thing Sumana linked to might indeed be helpful, but probably only at longer texts. At short texts there is not enough critical mass to be precise.
Lodewijk
2013/5/22 MZMcBride z@mzmcbride.com
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?
I'd recommend doing what we do on the wiki to make topics easier or more accessible: include a lot of links. The blog is worryingly low on links in each post, given that it's the blog of Wikimedia, king of [[links]]. Perhaps linking needs to be made easier in WordPress?
I'm not sure there's much else to be said other than "avoid the use of (unexplained) jargon and write clearly and concisely."
The Wikimedia blog is made up of several sub-blogs. The tech blog seems like it would inherently be more... technical than the community blog or the fundraising blog. Unless the larger issue is the audience question. That's a bit of a rabbit hole, though.
MZMcBride
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Yes, use the <ABBR> tag in HTML.
(Apologies for top-posting, on mobile at airport) On May 22, 2013 8:07 AM, "Lodewijk" lodewijk@effeietsanders.org wrote:
I think what is even more helpful to people, is to avoid abbreviations as much as possible, or explain them. For example:
- Up-Goer 5 (but there was a link next to it - which allows you to guess
what it means)
- SMOG (the stuff that is in the air, right?)
- FKT
Usually this kind of abbreviations (without in-text explanation) makes texts much harder to read. Even a link to an explanation is usually less helpful than a few words of what it actually is (especially when reading offline - yes, that world still exists).
Anyway, aside from that, I think Quim has a point that jargon is much more dangerous than complicated words. However, don't underestimate the amount of non-native volunteers. I have all too often heard at meetings that people felt insecure to participate in a discussion because they felt it was above their level. Some native speakers have the habit of going all wild with complicated words (this is not too common, gladly) and then you realize that texts with long sentences with lots of long complicated words are much harder to understand, even if you understand each word by itself.
So this score thing Sumana linked to might indeed be helpful, but probably only at longer texts. At short texts there is not enough critical mass to be precise.
Lodewijk
2013/5/22 MZMcBride z@mzmcbride.com
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?
I'd recommend doing what we do on the wiki to make topics easier or more accessible: include a lot of links. The blog is worryingly low on links
in
each post, given that it's the blog of Wikimedia, king of [[links]]. Perhaps linking needs to be made easier in WordPress?
I'm not sure there's much else to be said other than "avoid the use of (unexplained) jargon and write clearly and concisely."
The Wikimedia blog is made up of several sub-blogs. The tech blog seems like it would inherently be more... technical than the community blog or the fundraising blog. Unless the larger issue is the audience question. That's a bit of a rabbit hole, though.
MZMcBride
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
Wikimedia-l mailing list Wikimedia-l@lists.wikimedia.org Unsubscribe: https://lists.wikimedia.org/mailman/listinfo/wikimedia-l
wikimedia-l@lists.wikimedia.org