News for hackers. Stuff that matters.
Re:Writing great documentation by p3ll0n on Monday June 14, 2010 @05:44PM (#1431114)
Four rules that should be tattooed on the back of every technical writer’s hands so they can’t accidentally forget it.

1. Poor grammar and bad writing are often a sign of poor comprehension.

2. Good documentation takes time.

3. Deep expertise is not automatically a prerequisite for good documentation.

4. Don’t let working cultures that put too great a premium on knowing everything dominate - i.e. being 'in the know' should be a tool for helping others up rather than beating them down.

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).

Re:Writing great documentation by jamesbritt on Monday June 14, 2010 @07:45PM (#1431379)
"Deep expertise is not automatically a prerequisite for good documentation."

A beginner's mind is a big plus.

When documenting my stuff, or writng tech articles, I have to try hard to recall what things tripped me up or what things feel obvious now but were were hardly so when I started.

Re:Writing great documentation by moe on Monday June 14, 2010 @06:46PM (#1431281)
5. Your links should not lead to a 500 Internal Server Error

</tongue-in-cheek>

Re:Writing great documentation by alextp on Monday June 14, 2010 @07:09PM (#1431321)
> 1. Poor grammar and bad writing are often a sign of poor comprehension.

This is true, but I'd add "at least be the poor reader".