News for hackers. Stuff that matters.
Re:Writing great documentation by jules on Monday June 14, 2010 @06:15PM (#1431206)
> 1. Poor grammar and bad writing are often a sign of poor comprehension.

Or a sign of a non-native speaker.

Re:Writing great documentation by billswift on Monday June 14, 2010 @08:04PM (#1431416)
Even in a non-native speaker they are still signs of poor comprehension. If you are going to have someone write your documentation, they had better know the language. I have not bought from some companies a second time because their documentation was so bad.

And, truthfully, many non-native writers are as good as many natives. Non-native speakers can be more readily identified (if for some reason you want to) through unusual word choices or stilted (overly formal) grammar.

Re:Writing great documentation by jerf on Monday June 14, 2010 @07:28PM (#1431351)
There are other more reliable signs of the same sort of sloppiness that are independent of native language, which if I were analyzing a bit of documentation I would use. Using inconsistent terminology is probably the biggest one. I struggle with this myself.

It doesn't matter what a "widget" is within your system, but it ought to be one thing and stay that one thing and everything that isn't that thing shouldn't be a "widget". (I'm not even trying to choose a generic word to make a point; I'm literally between two sessions where I'm working on the documentation for my local "widget" concept, which isn't quite like any other widget in the world, most likely.)

Re:Writing great documentation by gloob on Monday June 14, 2010 @06:29PM (#1431244)
Is it common practice to let a non-native speaker write your technical documentation? (Honest question.)
Re:Writing great documentation by pietro on Monday June 14, 2010 @06:32PM (#1431250)
Yes. English is used everywhere and by everyone.
Re:Writing great documentation by j_baker on Monday June 14, 2010 @09:27PM (#1431537)
Regardless of whether or not it is the sign of poor comprehension, that's unfortunately the way it's regarded: http://en.wikipedia.org/wiki/Fundamental_attribution_error

If you aren't a native speaker, you should at least try to have a native speaker edit for you (resources allowing).