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.