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!
Advertisements