In a recent discussion on the Techw-l listserv, an academic was looking to find advice about the “bleeding-edge” trends in help authoring tools. Academics want to prepare students to succeed in the job market once they graduate, and since academics usually aren’t focused on tools, this person was looking for guidance.
One of the commenters on the thread made a particularly astute observation about bleeding-edge tools. Robert Lauriston noted:
This happens to me over and over: an engineer mentions a product that they think has great documentation. I look at their docs for a few minutes and see that (1) the product is very simple and (2) the docs are nevertheless only around 10-50% complete.
Some bleeding-edge tools are certainly available. As you probably know, lately I’ve been exploring Jekyll, which is a static site generator. Jekyll is simple in its design, as are many other bleeding-edge tools out there. (By the way, I dislike the phrase “bleeding-edge” for some reason, so I’m almost using it in a derogatory way.)
The problem with adopting bleeding-edge tools is that documentation requirements get so complex, you either have to abandon the simple bleeding-edge tool (which produces the modern web output), or you have to jerry-rig the tool with such complex workflows and coding that the simple tool becomes a Rube Goldberg machine.
For example, here are a few features (based on requirements) that I added to my Jekyll project that have made this once simple tool really complex:
Finding a way to do all of this with Jekyll (which was originally designed as a blogging tool but turns out to be flexible enough to allow you to do “whatever you want”) was challenging. I mean first, I had to figure out if it could be done. Then I had to make it happen.
The problem is that the ways to handle the publishing requirements have now made my Jekyll process pretty freaking complicated, and if I were to get hit by a bus (which is not unlikely given that I ride my bike to work through busy streets with commuters), my colleagues would either struggle to figure out just how to configure it, or they would abandon it for another tool.
Bleeding-edge tools rarely satisfy the requirements placed on tech writers. For example, I was looking more closely at Contentful, an API-based CMS that looks to be bleeding edge. Do you think you could use a variable within a topic so that the same content source might use a different term depending on the output? If so, I didn’t see that capability.
Or take readme.io. Looks cool, right? But what if you want to re-use the same chunk of content in multiple outputs. Not possible. (In fact, I don’t even think multiple outputs beyond basic versioning are possible.)
Interestingly, Confluence was mentioned as one of the bleeding-edge tools. If you’ve tried to re-use content with Confluence, or version content, you’ll see that it too gets complicated. And when you try to architect any kind of Confluence output into another HTML target (besides the built-in HTML output that is primitive), you’re also going to run into complexity.
As I was adding a new PDF output to a subset of our Jekyll topics the other week (troubleshooting a colleague’s configuration), I tried to decide whether my Jekyll Rube Goldberg machine was easier or harder than it would be with a DITA-based Rube Goldberg machine.
With DITA, you would be setting up keyrefs that leveraged different conditional attributes, and then you would be configuring your DITAVAL files inside a tool such as OxygenXML, and so on.
Here’s what I decided: Any system you use will get complex when you try to satisfy complex requirements. DITA is complex because it was designed from the ground up to handle complex requirements, as are other systems built for technical writers.
If you just have simple requirements to fulfill, the execution is a lot simpler. But technical writers are hired to handle complex publishing requirements. (If it were easy, the company wouldn’t need you.)
As a result of the complex requirements, technical writers often select help authoring tools and systems that have been specifically designed to meet the complex requirements that technical writers have. This means the learning curve for these tools is somewhat steep. It also means that you often sacrifice the modern-looking output and simple authoring workflow inherent in the bleeding-edge tools for a more fixed, traditional tripane output and complex workflow.
Occasionally I’ve heard engineers ask briefly about tech writing tools, and they throw out a comment like “why not just use Markdown and Github” or something. These same engineers rarely stick around to answer how you would handle the complex requirements using these simple tools.
I do value simplicity and strive to use the easiest solution possible. If a project were simple, why adopt complex tooling? However, there’s a case for laying the proper foundation to allow you to scale in more robust ways in the future.
Regardless of the route you take, in the end, you’re not going to escape the complexity inherent in the solution, no matter which route you take.
If you create your own custom solutions, you have much more flexibility to do what you want — you just need the right skills. If you plug into standardized complexity (like DITA), you can buy systems and platforms that remove some of the complexity for you and put it behind a closed door. However, making any modifications to some of these pre-built systems will certainly be daunting.
People want modern-looking, interactive websites. Then they also explain on that they need PDF generation, translation, multi-edit capabilities, single source generation, workflows, and document statuses, etc. By the time the list of requirements is finalized, about the only tools that satisfy them are more traditional tech comm tools.
So, sure, that looks nice and clean compared with the comprehensive documentation I’ve produced for a product that’s 100 times as complex. Robert Lauriston
Get new posts delivered straight to your inbox.
I'm a technical writer based in the San Francisco Bay area of California. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.