Favorite tech writing dogmas

I’m usually wary of dogmas, but some just won’t go away, they assert their eternal truth in uncanny ways. I’ve recently found some new ones, so I now have four five tech writing dogmas:

  1. A new tool will not fix broken processes.
  2. No matter how cool you are as a software company, don’t build your own help tool – it’s not worth it.
  3. Don’t invent yet another universal standard. – from xkcd’s How Standards Proliferate
  4. Following a style guide will not make you a good tech writer (unless you understand methods and processes such as topic-based authoring and single sourcing as well) – from Scriptorium’s The latest style for tech comm: adding value
  5. “No matter how much you try, you can’t stop people from sticking beans up their nose.” (This metaphor can apply to customers who use your documentation or to non-documentation managers who make decisions about documentation.) – from Jared Spool’s highly entertaining and insightful post

Your turn

What do you think: Are these some of the eternal truths in the world of tech writing? Have you encountered them? Or are dogmas inherently silly and evil? Please leave a comment.


4 Responses

  1. Those are rock-solid, Kai. Here’s one I live by:

    Do not trust yourself.

    Every time I forget that one, I am quickly reminded of it. Painfully.

    • Thanks, Bill. Indeed, frequently the mistake arises between the chair and the keyboard… πŸ™‚

      But I guess there’s a corollary: Do not trust auto-generated content. πŸ™‚

  2. Too bad that (1) and (2) don’t seem to be heeded where I work. Well, and (3) as well. πŸ™‚

    • Thanks, Mike. Yes, it’s amazing how prevalent these ill-advised practices are after all. I’ve since learned that (1) also strikes other departments in software companies. And that (2) also applies to other tools, not just help tools…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: