One of the facts of life when you write technical documentation and guidance is that it will get reviewed by other people, resulting in regular changes to the content as you try to follow shifting advice, conflicting feedback, and suggestions that sometimes even make sense. It doesn't help, of course, if the technology you are documenting is also a moving target.
I don't profess to be an expert in all the technologies we cover, but I generally have a good grasp of the fundamentals for each one - such as what it's supposed to do, how it does, it, and how you can use it. But I depend on reviewers and feedback to make sure I covered all the relevant points, and that what I've written is accurate as well as being useful.
Over the years, I've come across many situations where it's useful to write defensively in order to minimize errors and illogical content, and to reduce the work required to get the stuff finished and out of the door. While they might not be applicable to everyone, here's a few things to think about:
And finally, my own hobby horse: always remember the phrase "Time flies like an arrow but fruit flies like a banana". Use "such as x" rather than "like x" when giving examples of things...
I have a book called "Eats, Shoots, and leaves" that covers many examples similar to the one in your last paragraph. Some can be very funny! (And there is actually a joke that has "Eats, shoots, and leaves" as the punchline.
One of my favorite quotes is:
Not the wild heat of love's full passion
Nor the fierceness of the cold flames of hate
Can match the intense need of one man
To edit the work of another
Nice one - thanks Michael! You might like my ravings about the word "disparate" in blogs.msdn.com/.../top-10-tips-for-new-or-nervous-computer-users.aspx...