Complex tools versus simple tools

by Tom Johnson on May 10, 2014
categories: dita • wikis

1-11-2016 Update: For a related post, see https://idratherbewriting.com/2016/01/10/why-simple-tools-become-complex/.

Neal Kaplan's post on the Death of Technical Writing, which focuses heavily on comparing complex tools versus simple tools, has caught the attention of the tech comm world in a viral way. The comment thread on the post has some of the best insights I've seen.

A couple of months ago I posted about a simple way to create and publish documentation using Markdown and Google Docs. Then last month I started a series on DITA. Some people have written to ask me for my opinion of DITA and whether they should implement DITA in their tech comm scenarios.

Based on my use of DITA, here are my thoughts. If you can put together an authoring-publishing workflow that is form-fit to DITA, then using DITA can be a good choice. For example, if you're using Oxygen to publish to Oxygen's webhelp output, or using easyDITA to push to MindTouch, or pushing content into Antidot's Fluid Topics, or Mekon's DITAweb, or Componize's Alfreso integration, or some other defined DITA publishing solution, then I think DITA can be a good approach.

Where DITA becomes bulky and awkward is when you try to publish DITA into a custom solution without the funds to build the custom solution. In my situation, our content is in Drupal and there aren't any good bridges from DITA to Drupal, so the workarounds I've tried have been a bit too cumbersome to keep up.

DITA does have a lot of flexibility, so if you have about $10k to hire an XSLT developer to build custom transforms and other integrations, and another $10k for a development agency to connect DITA to your publishing platform, then you can plug DITA into your custom website in a way that probably works.

DITA does sort of fail when you're working in a highly collaborative environment, with expected contributions from other non-tech-comm team members. Few people outside of tech comm will structure content in DITA, and while there are Word templates with DITA structure underneath, my guess is that an engineer or product manager may resist them. Unless you have requirements for re-use, translation, or standard topic types across a large team of writers, DITA may not be a good fit.

I'm also not terribly impressed by the topic types in DITA. Much of the kind of documentation I write isn't neatly packaged into a list of steps or a concept. When you're providing code tutorials for programmers, things aren't always in a strict list format or strict concept format. They're a blend of the two.

In the end, which wins — simple collaborative tools like wikis, or robust publishing solutions like DITA?

Choose simple solutions if:

• You're collaborating a lot with other people who aren't technical writers.
• Other people who aren't technical writers contribute to the documentation.
• You don't need robust re-use capabilities (e.g., you just publish to one online source, not 5 different product versions in 10 languages).
• You're not translating your material.

Choose DITA if:

• You're re-using your content in significant ways.
• You're translating your content.
• You have a large team and need to standardize on an enforced structure.
• You're using an established DITA authoring-publishing solution.
• You have budget to hire XSLT specialists and developers to help set things up.

Developing XSLT expertise

One of the problems with developing XSLT expertise is that you become a tech comm tools publishing expert. I may be wrong, but it seems that companies can simply outsource that work to a tools shop, hiring someone to set up the XSLT and other publishing architecture in a one-time deal. Once it's set up, you no longer need the full-time XSLT knowledge in-house.

What companies need are people knowledgeable about their technology products. As a technical writer, I think it's more valuable to a company to spend my time learning programming languages and other industry or company technologies instead of XML publishing technologies. The company's technology needs should be at the forefront of a technical writer's attention. The authoring-publishing workflow should not consume the bulk of the technical writer's time.

Next: 1.7 What does DITA-structured help look like?