Hacker News Reader

Comment by p3ll0n | Hacker News Reader

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.

View on HN

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

Or a sign of a non-native speaker.

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.

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

Is it common practice to let a non-native speaker write your technical documentation? (Honest question.)

Yes. English is used everywhere and by everyone.

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

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

5. Your links should not lead to a 500 Internal Server Error

</tongue-in-cheek>

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

Reply on news.ycombinator.com