Help smash tech writing dogmas!

I confess: I have a couple of dogmas about tech writing – though I generally consider them detrimental to communicative, collaborative jobs such as ours.

By dogma, I mean here a firmly held belief that I assume applies universally, if only because I haven’t been convinced otherwise yet… 🙂

However, seeing how much I’ve learned from your great comments and opinions to my previous posts, I’d like to invite you to chip away at my preconceived notions. Maybe my dogmas are unfounded and silly…

So here goes, meet two firmly held beliefs that I’ve acquired over the years:

Don’t build your own HAT!

I don’t care how cool you are as a software company, I firmly believe that you should not build your own help-authoring tool (HAT), unless that is actually (part of) your business.

True or false? I believe it’s true: The initial project to build the thing is like reinventing the wheel, but you may actually get all the cool features you think you need and don’t get from a third-party system.

But I’ve yet to see a company that can sustain the required maintenance efforts: Development for profit goes before development for internal cost centers, and just about anything goes before documentation. So dev resources for the HAT are always scarce and low-priority. As a result, bug fixes, updates and enhancements to the HAT take longer than they should. Meanwhile, writers work inefficiently and with frustration which often brings down the quality of the help.

I also doubt it makes economical sense to continuously invest non-billable development time when you can get a third-party product and maintenance plan, usually for a fraction of the cost.

Don’t buy a tool to fix your processes!

Blame your tools all you want for why your documentation is bad and/or painful to create, I firmly believe that getting a new tool won’t fix that.

True or false? I think it’s true: Frequently, bad tools beget bad processes, but you need to fix your processes separately. Problems with the tool can be so obvious, they tend to obscure ill-designed processes.

Actually,  I recommend to fix the processes first, so you can then buy the right tool that supports them. A good tool makes it easier and more efficient to create good results, but good pots and pans don’t make you a master chef.

Have at it!

Please help out a fellow tech writer: Leave a comment and give some reasons, if you think:

  • Dogmas deserve to die, and these especially!
  • Dogmas are generally bad, but these are actually true!
  • Dogmas rule, and we need more of them!

5 Responses

  1. […] This post was mentioned on Twitter by Julio Vazquez, STCSoCal. STCSoCal said: Help smash tech writing dogmas! […]

  2. Funny, I have been thinking along similar lines, but I’m afraid I fall squarely into the dogmatic camp with this:

  3. Both points are good food for thought. I think what’s most important is not whether dogma is good or bad, but whether we are willing to look at all sides of a situation, test our assumptions, and determine whether an action enhances or impedes our ultimate goal: to provide clear, accurate information for our customers.

    So in thinking about your two points (don’t build your own HAT, and don’t buy tools to fix your processes), I wasn’t concerned about whether they constituted dogma…I appreciated that you raised these questions, stating your view, and inviting further discussion.

    (Just FYI, I do say “true” to both of these — I think it would be unwise to build a HAT unless there is a reasonable chance that doing so would enhance the quality of the help…and yes, it’s a mistake to think that a tool can fix a bad process, although if a process is analyzed thoughtfully, new or better tools might be part of the solution.)

    • Thanks, Lori. I totally agree that just about all is fair, dogma or not, if only it furthers our goal and improves our documentation.

      These particular dogmas come from watching too many people pursue other goals: Wanting to build a good tool or wanting to change the way they work. And both don’t inherently improve the help…

Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s

%d bloggers like this: