Search results

Is tool fragmentation in tech comm a good thing?

by Tom Johnson on Aug 5, 2014
categories: dita

One of the attendees from Alan Houser's recent presentation at InfodevDEC meetup in Virginia the other night noted the following:

Juxtapose this tweet about Alan's presentation with the recent WritersUA Tools Survey from Joe Welinske, which pretty much reflects the same trend.


Granted, there are a few predominant tools (the ones you always hear about). For help authoring tools, some common tools noted by the survey include Atlassian Confluence, DITA OT (and Oxygen and Xmetal), Madcap Flare, Adobe Framemaker, HTML Help Workshop (?), Robohelp, and WebWorks. But there's no clear pack leader. And there are a lot of tools with just a few users (the Long Tail effect).

Tool fragmentation is no doubt a trend. Take a look at the upcoming meeting topic for Write the Docs:

Over the past few years, Splunk has developed a wiki-based documentation platform that they liked so much they decided to open-source it to the masses. And they named it Ponydocs, after the company mascot (an animatronic toy pony, of course).

Chris, Rachel, and Russ will detail the evolution of Ponydocs from its humble MediaWiki origins, discuss the system and content architecture, and talk about structuring information in an unstructured environment where all employees can edit the docs (yes, you read that right).

Come and find out how this crazy thing works, and see if it might not be a docs solution that could work for you!

As if you didn't already have enough tools to choose from, now you can consider one with an equine theme: Ponydocs -- a spinoff of Mediawiki. (Lots of tools seem to spin off of Mediawiki.)

The other afternoon I found myself considering Document!X. Why? Because I want a push-button solution for converting comments in Java, .NET, and C++ source code into documentation that all looks the same. Document!X will do it for Java and .NET, but not for C++. Alas, there's no tool that will do it all.

REST is its own unique beast, with no tool automating source documentation (except maybe Swagger, which is less of a tool and more of "a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services").

Last week Mark Baker gave me a demo of SPFE, an XML architecture with its own markup and output, one that seems to be a better fit for the web. Rather than constructing massive tables of contents, you build affinities based on concepts (which end up working somewhat like tags). Even if it gets adopted, I imagine it will be years before it enters mainstream use.

Many view DITA as an industry standard for tech comm content, one that a majority of technical writers could leverage to publish help content. Unfortunately, it seems to require too many developer-ish skills to really be something the average tech writer can make work flexibly in all the different contexts and scenarios.

Without question, we live in an era of tool fragmentation. Those good ol' days when nearly everyone seemed to require the same tool (Framemaker, Robohelp, or Flare) are gone. Yet if you look at job descriptions, Human Resources groups still operate under the delusion that not only will the tech writing candidate know the company's technology platform (for example, Java or NoSQL or Linux), but also the exact tool the company happens to be using.

This leads me to the following question: Is tool fragmentation good for tech comm? Wouldn't it be better if we had a standard that pretty much everyone followed when working in tech comm?

Pros of tool fragmentation

One benefit to tool fragmentation is that it reflects widespread technical innovation. It's not as if there's just one tech comm company out there with the chops to create tools for documentation. No, there are many. And although tech comm doesn't seem to be a big market, certainly the proliferation of tools and vendors out there suggests that there's a great need for robust, powerful tools in this space.

The proliferation of tools also means that a lot of different tools are equally capable of providing solid help. So what if you use FAR HTML instead of Framemaker, or Help Console instead of Flare -- most likely you're getting the job done. You're helping users figure out how to use your software and other technical products.

Cons of tool fragmentation

Despite the pros, I think there numerous cons to tool fragmentation. First, it's hard to know where to pour your professional energy. If you want to deepen your tool skill set, it's hardly worth investing time in your existing help authoring tool since it's unlikely you'll be using it in your next job.

When there's a large community of people using the same tool, there tends to be a lot of helpful information around that tool. For popular tools, usually other people have already asked the same questions you have, others have already blogged about it, etc. In short, there's information to be found with online searches. This speeds up the authoring process and lowers the technical barrier to tool use.

When tools are fragmented, communities are also fragmented, since many communities come together around tool similarity.

Additionally, for more popular tools, there are often plugins and third-party add-ons developed around the tool. For example, OxygenXML has a plugin for Eclipse, a popular IDE. Those kinds of plugins aren't usually available for less popular tools.

Finally, unless there's a critical mass of users, new vendors are less likely to get in the space with new products.

DITA and tool fragmentation

Many vendors have embraced DITA XML and used it as the underlying architecture for their content. This is helpful because it allows tech writers to easily migrate content in and out of the tool. The tool becomes more like a platform that parses a particular structure, not something that forces content into a proprietary format.

Additionally, DITA has a strong sense of community across many industries. For example, the Yahoo DITA Users group has nearly 4,000 members. It seems like every sizeable company (which has lots of writers, content, translation needs, re-use, etc.) is using DITA, though their actual tools usually vary (e.g., SDL versus Ixiasoft versus Vasont).

Given its variety of users and scenarios, DITA seems to provide solutions for most of the common tech comm needs, with opportunities to scale to more sophisticated solutions if desired. For example, for simple publishing needs, you can get by with OxygenXML, publishing out to the built-in webhelp (for less than $500). For more advanced publishing, you can push the same content out to Fluid Topics, SuiteShare, DITAweb, Arbortext, or other DITA publishing platforms (for much more $$).

A time of transition

It could be that we're simply in a time of transition. As we move away from proprietary tools toward a common standard, maybe there's a period of fragmentation and exploration toward other solutions. But as DITA matures and becomes more ubiquitous, with a larger user base, it might pick up speed and at some point, catch exponential growth because it achieves a critical mass (just as products on Amazon or Audible with hundreds of reviews begin spiraling upward simply because of their popularity).

DITA technology is also appealing because it seems to apply across a wide swath of tools, with the capability of being the universal format that allows new vendors to quickly present a viable new tool you can migrate to tomorrow. In other words, whereas many standalone tools lock content into their proprietary formats, DITA is universal enough that you can plug into a whole array of different tools. In this sense, DITA as a technology helps move us beyond tools.

See the follow-up to this post, Benefits of tool diversity, part II.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.