Writing clearly

This guide has two purposes: to help write content that is easier to translate, and to help translate Wikimedia content effectively.

General advice

Every editor on every project should aspire to write clearly. If you actually imagine a world in which every single human being can freely share in the sum of all knowledge, that world would be one with clear, descriptive language rather than buzzword and jargon-laden language designed to confuse and confound. You cannot "freely share in the sum of all knowledge" if you cannot understand it.

Writing clearly requires you to think clearly first. Try and explain what you mean in plain and simple concrete words rather than abstractions. Work out what a policy or procedure will mean for readers, editors and anybody else who will be affected by it.

Clarity not managerialism

People who edit Wikimedia projects do so for altruistic reasons: they want to share knowledge by working together. For most people, it is a hobby they do for fun. Managerialist writing has infected many areas of life: school pupils are "clients", library patrons are now "customers". Everyone is a customer and all institutions must be customer-centric, and deliver innovative solutions to empower our clients.

We deal with this verbal clutter every day: at work, in school ("proactively delivering key learnings"), when dealing with banks, the government and all sorts of public institutions (even the church: who needs a priest when you can have a fellowship leadership team?). Finding and extracting meaning from this kind of writing is dull and inefficient. If you have to do it frequently, irritation and cynicism kick in. You start wondering why these people can't just write like human beings. Then you start thinking that they are either too stupid and too vain to write clearly and plainly, or they are writing in this obfuscatory way in order to deceive. When you start inferring that people are either stupid, vain or deceptive, it does nothing for your trust in institutions.

Understanding the Wikimedia Foundation, the chapters and the projects should not be like that. The tolerance people might have for jargon and buzzwords in their everyday life won't be there online. People want to understand what the Foundation are doing and how it'll change what they do as an editor or improve the experience for readers, not whether it satisfies a key performance indicator.

Writing for translation

• Use short sentences. More than one clause is dangerous; more than two, usually unnecessary.
• Use clear, simple words. Explicit, one-meaning words are better than vague words with many meanings. That being equal, short and simple words are better than long ones. If necessary, disambiguate your meaning in a footnote.
• Use words that will have natural translations in many languages, or are likely to be found in a dictionary. This sometimes means using flat words rather than context-rich words.
• Make use of repetition and self-similarity. Repeating the same word or phrase every time it comes up is sometimes considered poor writing style. When writing for translation, it is a real advantage. Don't make translators guess whether you intended the tiny differences between different ways of saying the same thing. Use the same language each time.
• Avoid passive voice when the subject of the sentence is known, as well as perfect tenses if the same meaning can be expressed without them. Both are often hard to translate into other languages.
• Avoid excessive elision. Leave in conjunctions and helper words where it makes the meaning clearer.
• Consider using prepositions liberally and avoiding grouping long phrasal groups composed of many nouns.
• More recommendations and guidance sources are provided in the Tech News manual.

Neutral English first

A text written for translation should be clear and unambiguous. It should not necessarily be the same text that will be published for the language in which it is written. For example, if you are writing original copy in English, you will want to prepare two documents:

• A neutral English-language version as a basis for translation
• A version for English-language publication

Typically, the version as a basis for translation will be different — less exciting, more simply and colourlessly written, but more easily understood — than the published English version. On can think of the relationship between these documents as one of translation between two variant of English: a rich, colloquial English and a simpler, more international English.

Translating Wikimedia content

General translation

1. Is the text in question ready for translation? Is its working frozen, or still undergoing editing?
2. If the text is still in flux, translate it very hastily; and link directly to the historical revision you were reading when translating. This can help future translators. If you can afford to wait until the original texts are finished, do so.
3. Once the text is ready to translate, translate it verbatim. Then go over it to improve it in the local idiom. Make sure to use local conventions for dates, numbers and locations.
4. If you know more than one of the languages it is already in, cross-reference what you have written with a second 'source' language.
5. Ask the original authors, or other translators, about any questions you have regarding wording or style.

Wikimedia project content

• Preserve deep citations and edit histories.

  Note carefully which content you were translating, and the exact revision you were working from (if appropriate). Let editors of both source and target pages know that you have done this.

  Make sure that interwiki links exist between the articles, if they are on the same project; else [if you are offering an excerpt of Zola translated into Spanish, from a Wikisource article] be sure there is an external link to the exact content translated.

Wikimedia meta-content

• Announcements: Be sure it is clear that the announcement is a) a translation (listing which languages the original was written in), and b) under development, until it is ready for public release.
• Policy changes, votes, meetings, events: Be sure all dates for voting deadlines, and for the implementation of new policy changes, are up to date and in the right timezone. Be sure any links to discussion pages link to pages in the appropriate language.

Advice from the experts

English

• Writing for translation

  A booklet from the CdT (Translation Centre for bodies of the European Union), especially for longer texts but always valid

• Free guides from the Plain English Campaign
• George Orwell, Politics and the English Language
• As of 2015, the PISA translators, who work in 80 languages, are developing a translatability assessment method, but the criteria have not been published yet.
• English is not everyone's native language here. Avoid jargon, unexplained-acronyms, and obscure cultural references. Try to read incoming communication by focusing on the (AGF) intent, and not the specific word choices.

All languages

• How to write clearly
  • Booklet from the European Commission and the Directorate-General for Translation.
  • Ten hints in ten quickly-read pages; available in 23 languages.
  • Remember that Wikimedia terminology is even more obscure than the European Union's, that our translators are not full-time Wikimedia translators and that we more often risk leaving things out of context.

Advice from the projects

English

• Wikinews:Style guide on English Wikinews:
  • The Wikinews style guide is aimed at producing understandable and informative articles readily understood by the majority of readers.
  • Write to be easily understood, to make reading easier.
• Help:Writing definitions on English Wiktionary:
  • Write with simple grammatical structures rather than complicated ones. Limit the use of dependent clauses and phrases, whether set off by commas (or parenthetical). If many such additional modifications are needed in a definition, then that definition probably needs a thorough rewrite.
  • Avoid bombast, and get to the point. Padding an entry with superfluous verbiage may sound impressive, but that's not the purpose of a definition. Clarity, brevity, and conciseness are better when writing definitions.
  • Avoid polysyllabic monstrosities in the amalgamation of lexicographic phraseology. Don't use big words if you can avoid them. They may be fun, but in a definition they tend to confuse people more than help them.

See also

• User:Tom Morris/WMFers Say The Darndest Things
• Glossary