I’m about to commit heresy, but stay with me on this
I am in despair for our tools in technical communication right now. Here’s why.
I’ve spent the past 4 weeks or so evaluating tools for a client. They have some pretty simple and common pain points, listed here in no particular order:
- Collaborative authoring
- Content reuse
- Single Source source files
- Workflow with reviewers and editors, including Audit trail/version control
- Easily import from existing tool
- Auto sense content reuse possibilities
- Output to HTML-based help, PDF and Ebook?
- Easy interface for authors
- Localization project tracking of some sort
This shouldn’t be hard
In my experience, this is a pretty basic list of needs. Most tech comm groups have these pain points and need them solved.
But after reviewing tools for almost a month, I’ve not found anything out there that meets this list AND doesn’t cost $100k and months of customization to make it work.
A fast overview in which I carefully DO NOT name names
There are a lot of tools out there that, if you are willing to change your workflow to what the vendor wants it to be, some of this can be done for a shrink-wrap price.
One tool has potential to be the right solution except one important feature on this list is so horribly terrible broken, it’s beyond embarrassing. I reported the issue and they responded back that all development on the current version is stopped while they focus on the next version. No estimated delivery date for the next version is available.
In other words, the compelling reason you would choose that tool over the others doesn’t work and they’re too busy on the next version now to fix it.
Another product I was interested in had all the authoring and workflow stuff my client needs but you have to use the DITA Open Toolkit to publish out to anything. Meaning after my consulting is done, the client would most likely have to bring me back to change anything. That’s not nice to do to clients.
All other DITA options are either vastly too expensive OR require the same messing about with the Open Tool Kit.
Another vendor has a nice solution but you have to use at least 2 of their products to get the single sourcing the client needs. And from what I read on the lists, this integration hasn’t worked in any version yet. Yes, some people have gotten it to work but it takes special magic juju to do it. I can’t recommend a set of tools that are SUPPOSED to work well but actually don’t.
And so on.
How can this be?
I’m stunned that we have so few options for a tool that does the basic workflow in technical communication. Technical communication is at least 50 years old and we adopted the computer fast. The basics of how we do what we do have not really changed in the last 10 years.
Yes, we’ve gotten more connected and electronic but a review is a review, whether it’s on paper or online. The process of how we do what we do has stayed pretty stable. Our tools vendors say they are trying to keep up but by and large, the tools seem to be basically broken, in that they do lots of stuff but the core features that cover how we do what we do are not there.
So how is it that we don’t have any tools that actually solidly do the workflow? If you want to cobble together a set of tools, customize the heck out out of them, you might have something that generally works. Generally. Sort of. Most of the time.
Please don’t hit me with all the reasons why <insert tool here> is the way to go. I’ve got a recommendation for my client that does most of what they need. It’s the closest of the available affordable tools to what they need.
Is this just me?
Am I the only one who just despairs about the state of our tools in tech comm right now? Am I expecting too much from an industry to meet our easily articulated common pain points in a solid way?
Is anyone else encountering this craziness?
18 Comments
Trackbacks/Pingbacks
- Madcap Flare and Source Control in the Cloud | Sharon Burton - [...] a conversion and clean up project for a client. I recommended that they go with Flare because it met…
When I saw the list of requirements, I quickly recalled how the technology development clients approach service providers. For example, many ecommerce businesses need:
– User registration and profile management
– Products and product-category management
– Wishllist
– Shoping Cart
– Online payment system
– Order management
– Admin has secure CMS to manage products, payments, orders, transactions, SEO, static content of site, graphics, and basic reports.
For technology, five out of ten clients say that they are open to use Drupal, Magento, Joomla or even WordPress. The fact is that generally all these frameworks meet requirements of all clients, or a particular framework may not work for a specific client requirements.
Same is true for technical documentation tools. Even if we find a tool *ABCDE* that meets basic documentation requirements, a few clients will have some unique requirements (expectedly). And I guess this is what makes our work challenging (shall I add enjoyable?)
Have you looked at the Altova XMLSpy (& more) packages? I was using that years ago, and liked it because you could use databases/xml and work in the code. There were other reasons why I liked it as well. It looks like they have single-sourcing output, too.
Thank you A LOT for the article … it describes VERY exactly the problem I have here for our little documentation team (maybe except the “Auto sense content reuse possibilities”). I’d like to know names, too, maybe not public?
Send me an email off-line and I can tell you what I have chosen and why.
Hi Sharon,
You are certainly correct that this is a very common list of requirement. How can it be so hard? Alas, just because the requirement are common does not mean they are achievable.
The basic problem, and it has been this way for at least the last two decades, is that tech comm expects to get a certain kind of result from a certain kind of effort, and the two just don’t match.
The fundamental problem is this: you can’t get pigs out of sausages. If you want a system that can produce sausages and pork chops, and ham, you have to start with pigs. No tool or process will let you start with sausages and create pork chops. No tool or process will allow you to start with ham and make pigs.
In order to get meaningful levels of automation for things like collaborative authoring, single sourcing, content reuse, and the discovery of reuse opportunities, you have to treat your content as structured data. Without that level of structure, there is just no way for a tool to reliably automate these functions without requiring huge amounts of human intervention.
But if you want to easily migrate content from an existing system that is not structured, you have a pigs-out-of-sausages problem. The structure simply isn’t there, and so there is no easy way to do the conversion. Similarly, even if you are not trying to create structured data, if the old system is sausages and the new system is ham, there is still no easy way to do the conversion.
Of course if you keep pigs, you still have to deliver ham, pork chops, and sausages, and making sausages out of pigs, while feasible, is a proverbially messy business. Achieving the formatting of content to a specific design from structured data will always be a messier process than creating it WYSIWYG.
And then there is the question of what it means to provide an easy interface to authors. To many, it simply means WYSIWYG, and you can’t get reliable structured content from a WYSIWYG interface (XML content, certainly; structured content, no).
You can, in fact, provide an easy interface for authors to create structured content, but this means designing a structure specifically for authors that ask them for information they already have in terms they already know. It is not an editor issue, it is a structural design issue.
Unfortunately, most structured writing systems, DITA in particular, expect authors to work in structures designed from the publishing system backwards, requiring them to supply information they don’t have and interact with the internal workings of the publishing system, which they don’t understand.
So, tech comm must ultimately decide. If they want to be able to do all the collaboration, reuse, and single sourcing they ask for, they will need to start thinking of, and creating, their content as data. Until they are willing to do that, waiting for the tools to mature is like waiting for someone to invent a machine that can make pigs out of sausages.
One of the biggest problems with structured writing systems, is that people tend to write their business requirements based on their existing WYSIWYG/DTP processes, designs, and workflow (something I blogged about recently: http://everypageispageone.com/2012/05/11/the-design-implications-of-tool-choices/).
Structured authoring systems that attempt to accommodate such requirements become vastly more complex, expensive, and fragile than they would otherwise need to be, and don’t work as well as they should, because they are not really getting the data they need.
This naturally gives people the impression that structured writing is inherently complex, expensive, and fragile, which tends to make them protect themselves by specifying more and more stringent business requirements based on their old way of doing things.
The only way out of this is to rethink the process, workflow, and design based on a structured model without imposing artificial requirements from the DTP world. As a comparatively trivial example, the design possibilities for presenting structured content are very rich, but they are different from the design possibilities of DTP. If you create a design that is optimized for structured content rather than trying to reproduce a design created for DTP, things get a lot less messy, and you get to add some powerful design elements that are too expensive to achieve with DTP methods.
Short of that, your shopping list, common as it is, simply brings us to an impasse — the same impasse we have been at for at least two decades. You can’t make pigs out of sausages.
For the past several years I’ve thought that part of the tech comms tools problem originates from having used *authoring* as the starting point for any tools design. Later, after some amount of content has been authored, somebody says, “Hey, we really need to somehow start managing this stuff.” So some sort of ex post facto content management “strategy” is then bolted on to the workflow.
Imagine if instead the starting point for a given tool’s design began with management, et cetera. Only after the content management issues had been designed and proven would an authoring tool that feeds into that strategy infrastructure be designed and implemented.
I believe there are two reasons this tech comms version of the Copernican universe, in which *management* (a.k.a. the sun) rather than *authoring* (a.k.a. the earth) is not currently the center of our tools universe.
The first is that content management has only recently become a mainstream issue. I for one am amazed at the suddenness at which content management transitioned from being a Big, Expensive, Complex consideration to being considered by all but the very smallest tech comms teams.
The second is that vendors have a less-than-zero incentive to enable teams to produce truly interchangeable, as in wholly standards-based, bodies of content. If one has a body of documentation content, and one can readily dump an unresponsive tools vendor for another more responsive vendor with little or no pain, then the vendor is denied its regular revenue stream for selling “upgrades” that consist of few if any “features” anybody actually wants.
My head’s bobbing up and down in complete agreement. Was working with a client last year to find a tool that suited their needs. The best tool out there seemed to be Doc-o-Matic… didn’t make them happy. And I understand, because it had a crappy workflow and obscure documentation (another topic: why do technical documentation products have lousy documentation).
They shook their heads in disbelief, and sardonically wondered if they should shift from developing their product to a product that would satisfy their needs (and the needs of other software development organizations).
I think the problem lie in the fact that a lot of the tools were geared around creating CHM fies, and the world has moved on since that format was created. DITA has about a better process than necessarily about a better output.
There are tools out there that will do nearly all of the items your list – there are low cost documentation wikis which will pretty much all, apart from: Auto sense content reuse possibilities and Localization project tracking of some sort.
And your statement “There are tools out there that will do nearly all of the items your list” is exactly the problem. It’s “nearly” for all the tools. The one product that was a great contender was so terribly horribly broken in the one feature that set them apart, I can’t even demo it as a candidate tool. I’d look like an idiot.
These pain points are not unusual or uncommon. Why don’t our tools address these as the basic problems to solve?
We’ve had clients engaging us to look at new tools and processes, and so far, none of them have asked for Auto sense content reuse possibilities. Not everyone will want all the features you listed and th 80/20 rule may kick in. However, I agree there is an issue with the tools.
I don’t like to blame the software vendors for the current state of the tools. MadCap, for example, has done good things in the direction of reviewing content, DITA and localization. They are working in a niche sector where there is little clear direction from the former leader (Microsoft) or from the profession (Technical Writers) as to which features are wanted. Everyone in the profession needs to take responsibility.
Hi Sharon,
Your list of requirements at the beginning does not include “client must be able to easily make changes to output,” but that is introduced halfway through the article as a showstopper issue for the Open Toolkit. (I am not disputing — at all — the concept that modifying DITA output is a PITA.)
As always, this issue comes down to business value. Is the cost of DITA OT maintenance an unacceptable hit? If so, something on the original requirements list will probably have to go.
Do I share your despair? Not at all. I think that our delivery requirements (and priorities) are changing rapidly. Right now, the tools aren’t keeping up, which means lots of custom configuration for exacting requirements.
You’re right, Sarah, I didn’t explicitly say the client wants to brand the output because to me that’s inherent. Every company wants their tech docs to look like they came from their company and not just simple text.
And the cost of the OT is such that in fact, one of the things on the list is being thrown overboard. The tool I think will work best for them doesn’t quite have something we were hoping for.
But branding the output is not something that can or should be thrown overboard. We’ve been able to easily do that since the days of Winhelp.
No, but the idea that any tech writer has complete control over the output and can change formatting at will might have to go.
Fortunately, this is a small group and they work well together. They should be able to work with a standard list of format tags developed for them. They did well in the previous tool in this regard.
Thanks for this, Sharon, putting words to what (I’m sure) a lot of us are frustrated by. After over 25 years doing this, I’m still waiting for the killer documentation app. I’ve given up hoping for this mythical “With just a few clicks!” as long as the software manufacturers don’t practice what we preach–“KNOW YOUR AUDIENCE!” It’s not difficult–we’ve been asking for these things for years. And what do we get? Bug fixes called new features. A slightly easier way to do print documents from a mostly online Help tool. HTML 5 output before anyone really needs or asks for it.
I *DO* wish you’d name names, though. Perhaps only by revealing the guilty parties can we really have a dialogue with them and start seeing what we want and need and not what they want to give us.
*I* can’t name names. Having worked for 2 vendors, I think it’s bad form.
If you don’t need HTML5 now, you will do very soon. It’s a critical way of offering content on tablets. Given it’s predicted every home in the US will have a tablet by 2015, it’s great Doc-to-Help, WebWorks ePublisher and Flare support HTML5.
I couldn’t agree more, Sharon. I’ve been despairing about this same topic for years. And if you throw in a way to avoid using “conversion output” (the dreck you get when something is changed from one format/tool to another that you can’t control and have to learn to live with) it gets even worse.
Recently I have been doing battle with a pair of tools – owned and marketed by the same company – that just plain don’t play together nicely. Why? It’s not rocket science. These tools have been around for coming on 20 years and they still haven’t gotten it figured out.
The closest I’ve come is to use a website content development and management tool. It fits almost all the requirements (getting content into it is a challenge), but it lets you do most anything.
So – why is it impossible or prohibitively expensive? Are we that small a niche market? Over small things we as a profession are often overly persnickety, but in this case when I would expect to hear loud vocalizations of opprobrium, scorn, and contempt, all I hear is crickets.
Heresy? No. Plain unvarnished truth? Yes.
My 2¢,
JG