Wiki Life: English Tips


This post is intended primarily for authors writing in English as a second (foreign) language. Writing anything in a foreign language is hard enough, writing in Technical English is even trickier.
If you are unfamiliar with writing Technical documents of any kind then there might be some tips even if you're English.

Don't Write as I Say

Written English generally and Technical English particularly is quite different from English as it is usually spoken "Like wot is said, man… innit."
Entire courses are available on Technical English. You could take a course but maybe just read a few MSDN articles by native English speakers and get a feel for it. 

Technical English is also close enough to something called "Plain English".

Simple sentences

Count the number of words you put in a sentence. If you go over 20 then that is a long sentence. Long for English, that is. Some other
languages seem to encourage particularly long sentences with lots of commas.

For example.

"Rather than using commas to break up a sentence, consider breaking up your long sentences into several shorter ones."

Could be:

Long sentences can often be broken up into smaller ones. Consider whether a separate sentence might work instead of a comma.

Read up on "Plain English". 

No Filling

People often start conversational sentences with "So…. " or "now…." or "Actually…". These words are called
"Fillers". The speaker's purpose is usually just to defer constructing the meaningful part of the sentence. The speaker has more time to
think about what to say without leaving silence or maybe avoids someone else butting in.
Another equivalent is "Ummmmmm….".
You have plenty of time to think things through. Remove any fillers.

Empty Emphasis

Certain words are used in Conversational English to emphasise the speakers point. Such emphasis is frequently over used in conversational English and should only be used where sparingly. Some words but which have no place in an
article. Swear words are one very obvious example which readers are hopefully already well aware of.

Less obvious empty words are "Totally…" or "Absolutely…" or "…. Like".

Just to complicate things it should be noted that all these words have valid usage, like.

Oh

That's not one of them though. 

Slang

Use of colloquialism or slang should be avoided unless somehow particularly relevant. Words like "Amazeballs" ( whatever that means ) and "innit" are inappropriate.

Seek help

If you have some good content but not so good English there are options. You can either ask someone you know to help or appeal to another Wiki Ninja. Obviously, they probably have other things in mind to do with their time than re-write a huge article. Even a quick 10 minute fix up could catch a few things though.

Ideally you would want a native English speaker but any review can help highlight parts of an article which are not clear. A proof reader of any sort is invaluable. Even yourself. It's surprisingly easy to just miss out something you should have explained.

View Andrew O'Neill's profile on LinkedIn
All my Technet Articles

Comments (11)

  1. Useful tips, thank you Andy

  2. Thanks for this article, from a French guy !

  3. Naomi N says:

    Thanks, Andy.

  4. Peter Geelen says:

    That’s the paradox of an international community, right? Do best what you’re good at, your own language, and ask help from someone that excel in their native language, to guarantee high quality community content..

  5. Andy ONeill says:

    I would say that’s the synergy of the wiki at work. Elsewhere you write an article and you need to get any help before it’s published. In the TnWiki you can publish and then people improve the content.

  6. Great point, Andy! I do love that about the Wiki.

  7. Danish Islam says:

    Very useful tips. Will definitely use. Thanks Andy.

Skip to main content