5 ms·
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 ofte
by p3ll0n 16y ago
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.
- jules 16y ago> 1. Poor grammar and bad writing are often a sign of poor comprehension. Or a sign of a non-native speaker.
- gloob 16y agoIs it common practice to let a non-native speaker write your technical documentation? (Honest question.)
- pietro 16y agoYes. English is used everywhere and by everyone.
- jerf 16y agoThere 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.)
- billswift 16y agoEven 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.
- j_baker 16y agoRegardless 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 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).
- moe 16y ago5. Your links should not lead to a 500 Internal Server Error </tongue-in-cheek>
- alextp 16y ago> 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".
- jamesbritt 16y ago"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.