If you live in a wealthy, industrialized nation, automation touches just about every aspect of your life. From the products you use to the spaces that you inhabit, nearly all are produced by machines or regulated by automatic controls. World-leading companies invest hundreds of millions of dollars to stake out new frontiers in automation, such as space technology and self-driving cars, promising greater safety and productivity.
Why this drive to automate?
Sometimes automation enables feats beyond human abilities, like landing the SpaceX Falcon 9 rocket from space on a tiny platform in the ocean. Mostly the basic economics of industry drive automation.
Industry is systematic labor to create something of value. The incentive to maximize value spurs producers to increase efficiency and decrease cost. Labor is expensive. Automation lowers the cost of labor, either removing it from the equation entirely or multiplying the productivity of the individual worker.
In the “removing labor” model, the highly skilled, expensive artisan is replaced by the low-skilled, inexpensive line worker who, in turn, is replaced by a robot. In the “multiplying labor” model, a single worker manages a machine or system that does the work of many workers.
Employers love automation, because per-unit costs stay low. Consumers are happy because automation drives higher quality and that low per-unit cost translates into a wider variety of high quality, affordable products. The workers… not so much. They face some hard choices if they have any options at all. Both the artisan and the line worker can try to carve out a niche for themselves as boutique producers, retrain to do something else, or retrain to build, run, and maintain the machines that put them out of work.
So where should the users’ advocate stand on automation?
Consider that a technical writer, a hybrid beast, straddles the industrial (“technical”) and the artisanal (“writer”). Despite this unique position, we are not immune to the vagaries of automation, globalization, and other business trends. I started work as a tech writer on a team of six. Then I managed a team of four. Now I’m the company’s sole writer.
I take pride in my craft, but the hard reality is basic economics: No matter how lovingly created, my work isn’t worth much if it doesn’t make business sense. Complete, comprehensive, and clever documentation for its own sake isn’t justifiable. Instead of trying to justify hand-crafted, artisanal doc to my employer, I constantly explore ways I can use automation to, as FrameMaker guru Matt R. Sullivan puts it, “maximize [my employer’s] ROI on documentation by driving down the hours required to create and manage content.”
As a tech writer, how are you using automation to leverage your productivity? Should we ask whether you use automation to improve productivity?
To be clear, I’m not suggesting that you automate content creation, which would be a sort of Holy Grail of artificial intelligence. An AI that sophisticated could gather source information, synthesize useful content attuned to audience needs, domain context, and business requirements, and would then iteratively improve the content delivery based on feedback. This superstar AI would wipe the floor with the Turing test and would surely have more pressing and lucrative applications than generating user documentation. In fact, it would likely replace documentation, training, and customer support altogether. Maybe even the customer.
So, I am not talking about replacing writers with robots.
I’m talking about adding automation to your arsenal of tools and directing its power to:
- Free you from mindless, repetitive work so you can devote your time and talent to your users’ success.
- Extend the capabilities of your tools.
- Extend your own capabilities.
Ultimately, I would rather be curating content, responding to user feedback, and working to anticipate my users’ needs than hiding out neck-deep in the weeds of my doc systems. Here are a few ways I use automation to keep me sane, productive, and employed.
Authoring Tools
Authoring tools form a base layer of automation that I often take for granted. I really shouldn’t. For example, I built my first online help system by hand. It wasn’t 1975, so I didn’t have to shuffle decks of mainframe punchcards or flip toggle switches to enter binary opcode on an Altair 8800. It was 1998, so I typed out my HTML frameset into a text editor tag by tag, managing hyperlinks manually, and debating important details with myself, like whether I should use uppercase or lowercase tags.
This all made sense because in 1998, I was a baby tech writer (my labor was relatively cheap), and it was essentially a pilot project for the company’s first-ever online help. I’m proud of my work (I think I’ve mentioned it in nearly every column so far). I never want to do it again. Not only was it exacting, grueling work, but no users care about a help system made from hand-tooled, minimally processed code. Why would they?
Today I work in a WYSIWYG tool that allows me to get down and dirty with the source when I want to, but otherwise takes care of the boring, repetitive, error-prone details of applying tags and styles.
If you have a documentation task, chances are there’s a tool out there that’s suited to the work. With so many tools available like Flare, RoboHelp, FrameMaker, InDesign, <oXygen/>, DITA Open Toolkit, just to name a few, you’re not doing anyone any favors reinventing the wheel, not yourself, not your employer, and not your users.
Macros
Automation is so important and so powerful that many applications include it right out of the box in the form of macros.
The ability to record and replay UI actions brings automation within easy reach of folks who don’t code. A small investment can yield extra time in your workday.
I took my first baby steps in automation with macros in Microsoft Word. As much as I find Word a head-scratching, hair-pulling experience, its macro recording and action-mapping capabilities have saved me a lot of time and trouble over the years.
I also use macros in Photoshop (where they are called “actions”) for batch processing screenshots, converting file types and normalizing color depth and display resolution. Photoshop extends the idea of the macro to the “droplet” that allows you to drag-and-drop your files for processing onto an icon in the operating system without even starting Photoshop.
For applications without built-in macro capabilities, third-party solutions can graft the functionality into your environment. I don’t have much experience with these, so a search for “macro recorder” should yield more for you than I can type here.
Off-the-shelf Plug-ins
Authoring tools, even with macros, are general automation solutions. They meet the requirements of the greatest number of users to translate into sales for commercial tools and user adoption for open-source tools.
What if your needs fall outside the target demographic?
For commercial applications, armies of boutique developers, hobbyists, and enthusiasts reconnoiter, strategize and then attack the business of building more focused solutions as plug-ins for your plain-vanilla OEM tool.
For example, when I worked in a FrameMaker shop, I curated a toolbox of plugins, mostly from Silicon Prairie Software. For the cost of a few dips into petty cash, I added style, cross-reference, and table management functionality that not only lightened my day-to-day workload, but also reduced a style-guide migration project from days to hours.
If you work with open-source tools, you benefit from the practical philosophy that guides their development. Open source projects are built by community effort for the common good. They actively encourage extending the base product. As long as the community is large and vibrant, you’ll likely find an extension or two that meets your needs.
DIY Plug-ins
What if your demands on your tools are even more esoteric? Your searches and your forum posts all come up empty.
Some boutique developers and hobbyists take commissions and will build you a custom solution. I’ve never done this, but I expect that these folks don’t work for petty cash.
Instead of laying out the money, build ‘em yourself!
I don’t mean to sound glib. Such projects require a significant investment in time and someone motivated to do the work, but if you don’t have the capacity in your budget, maybe you can flex your schedule to develop your own extensions.
It started for me when I led the company’s efforts on API doc and I quickly discovered a big gap in the first releases of Javadoc. It didn’t include a facility for internal doc comments. I could deliver comprehensive API doc to our customers, but when my own developers discovered the resource, loved it, and requested their own edition enriched with internal details, I could only shrug my shoulders.
I took the failure personally, both because it was my primary job function and because I hate feeling helpless. Duly motivated, I dove into the Javadoc Tool. Taking advantage of Java’s pseudo-open-source nature and some extraordinarily generous support from a senior developer, I added my own @internal tag, which was immediately adopted by my eager engineers.
I then turned my automation energies to FrameMaker where I managed a suite of branded docs. The list of brands was growing beyond my ability to brand manually. Adobe offered the clearest solution in the FrameMaker Developer Kit (FDK), a set of C libraries and header files that promised direct, automated access to my FrameMaker documents. With the FDK’s excellent documentation, I had the first version of my branded build process working in production within weeks, generating scores of brands of PDF docsets for our customers with every release. Automation made me look and feel like a superhero.
The end results of my automation projects weren’t just the documentation. I got a lot of Java and C programming experience and I developed a healthy loathing for content locked into closed, proprietary source files.
Scripting
I did some great things in FrameMaker, but my plug-in was cumbersome and fragile. My doc builds would crash due to bugs in underlying libraries that I had no control over. Maintenance was laborious, requiring a recompile for every update. Dependencies on multiple third-party products, including a very specific edition of Microsoft Visual Studio, left me feeling vulnerable.
I hate feeling vulnerable as much as I hate feeling helpless, so I looked for something lighter, more flexible, portable, and robust.
I found it all with scripting.
I started with simple file manipulation using Windows batch files, but when I tried anything slightly more complicated, I immediately ran into limitations. I then explored cygwin following the long-ago glimmer of my experience in Unix, which finally led me to scripting in Perl.
Within a few months, I replaced my buggy, clumsy plug-in with compact, reliable, easily maintained and extended Perl scripts. When I brought up my scripting accomplishments casually with my favorite senior programmer, he snorted “Perl? Why not Python or Jython or Ruby or anything but Perl?”
It took about six months for me to get over myself and the sting of his scorn. When I did, I checked out Python, rebuilt one of my Perl builds, and I haven’t looked back since. If you’re interested in why I dropped Perl so quickly for Python, check out Conor Myhrvold. It’s a long read, but his experiences run closely parallel to mine.
Now every documentation project of mine gets a scripted build. Depending on the project requirements, I can build multiple brands, draft editions for review, or internal editions with all the mechanical details like conditional tag expressions and file naming completely automated, invoked by a few command-line switches.
In addition, for online output, my automated builds handle a potentially grueling gotcha: post-processing of UTF-8 characters.
Weird things can happen to special characters like copyright symbols and open/close quotes in the mishmash of character sets and encodings that stretch between a server and a client application. The most sure, portable way I’ve found to add special characters to XML/HTML/XHTML is to use XML entities. Unfortunately, the WYSIWYG tool that rely on converts these entities to the UTF-8 byte sequence in Windows. This results in garbage when displayed by a client that either doesn’t recognize the encoding or flat-out ignores it.
My online builds include a post-processing step, replacing all the special-character byte sequences with those universal XML entities. I can’t just do a simple find and replace. My build needs to be aware of a source file’s encoding so that all of the smart quotes, apostrophes, ellipses, special bullets, and trademark symbols, are swapped out. It’s a quick and automated fix for an infuriating and embarrassing problem.
Don’t Just Do More with Less, Be More
Recently I was reminiscing with a long-time coworker about the heady days of the dot-com bubble when venture-capital money flowed like water and I enjoyed the camaraderie of five exceptional writers. My colleague reminded me that we had about a fourth as many products then. One writer doing four times the work that used to require six writers? “How do you do it?” he asked. He made it sound so grim and gritty, like I was the last contestant on the island in a season of “Survivor”. I admit there have been some very stressful and challenging times. but it’s been less “automate or die” and more a natural, continuing progression towards becoming the best users’ advocate I can be.
