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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: