From tech writer to DITA superhero
In the world of superheroes, technical writers could just slide down a pole or do a clandestine spin to transform themselves into DITA technologists. Of course, nothing is that easy, so what does the transformation from tech writer to DITA superhero really require?
If you’re thinking about becoming a DITA technologist (or are a manager looking to transform a tech writer into a DITA specialist), consider these prerequisite special powers:
- Are you a self-starter? You must be willing to jump right in and poke around the DITA Open Toolkit and to learn about the many technologies interwoven into it (Ant, XSLT, XSL-FO, and so on). If you have job responsibilities that consume most of your work day, you will need to find a way to reduce your workload to accommodate this exploration, or you’ll need to do it on your own time. Don’t like the idea of exploring, using, and inevitably breaking the toolkit? Then you’re not ready to become a DITA superhero.
- Can you learn by experience? A big part of mastering the DITA Open Toolkit is learning by experience. You figure out a fix and then reuse that technique to solve similar problems. If you can’t retain and apply (and reapply) your experiences, please don’t report for duty. (By the way, passive learning isn’t going to work—just sitting through a class or reading a book will not give you all the skills you need. You must get your hands dirty to learn the OT.)
- Can you think and work like a programmer? If the idea of tinkering with code does not appeal to you, maintaining the XSLT and XSL-FO transformations in the toolkit is absolutely not for you.
- Are you a dogged troubleshooter? The DITA Open Toolkit can be an annoyingly delicate creature. A coding error (a missing angle bracket, for example) in either source files or a transform will completely break your process, and the error messages you get from the toolkit can be extremely unhelpful. Be prepared to spend hours looking for needles in haystacks—Herculean patience and strong determination are required. Getting angry is not going to transform you into a DITA-smashing beast:
What special powers do you think DITA superheroes should have? Let me know in the comments below.
About the author
Ethan
Slightly expanding on the think and work like a programmer, try to think and work like a GOOD programmer. Leave quality comments in your code. The troubleshooting time you save with your comments will likely be your own.
Alan Pringle
Good code comments are indeed invaluable. And those of us in tech comm should be able to write short comments that distill the importance of what’s going on in the code.
Thomas Böttiger
There’s one more thing: you must be willing to sacrifice beauty for efficiency.
Sarah O'Keefe
Hi Thomas, perhaps your documents are beautiful, but I have seen a lot of really, REALLY ugly tech comm documents, so I find the “no more beauty” argument to be largely unconvincing. 🙂 I think that you can use DITA to produce professional, attractive documents. Maybe that’s a different post…
Alan Pringle
If you’re using the default DITA OT PDF transform and the Apache FOP processor, I would agree you’re sacrificing beauty. However, for Scriptorium’s books and for the content of various clients, we are using the Antenna House processor and customized PDF transforms. I can tell you output looks as good–or better–than what comes out of A Document Processing Application I Will Not Name.
Walter Hanig
The ability to extract sufficiently unambiguous requirements from your users is important.
Alan Pringle
Those requirements can be particularly difficult to extract if you need a new form of output. If competitors have stuff online, perusing that content can generate ideas, but be very careful about keeping comparison from becoming plagiarism!
Leigh White
Great post, Alan! I would add that you need the superpower of patience. As the DITA superhero, you’ll find yourself supporting all your team members who chose not to become DITA superheroes. While you’ll get lots of wonderful, valid, helpful comments from them that help you refine your stylesheets, standards, and processes, you will–unfortunately–also get the same questions a hundred times, and resistance from folks who want to keep doing what they’ve always been doing, just in DITA now. If you want to have a successful DITA implementation and not lose your superhero cape, you’ll need to meet all these questions and resistance with an encouraging smile and positive energy.
Alan Pringle
The soft skills you’re talking about, Leigh, are as vital as the technical smarts required for implementation. Excellent point.
Julio Vazquez
I agree with Leigh; patience is important. Not just with those who choose not to be superheroes but with yourself. There may be times when a specific problem chooses to be a Cheshire Cat and only grin at you while you try to figure out precisely why code won’t do what you want it to do. Sometimes this is because you’ve forgotten that you’re actually changing the wrong piece of code in the plugin that is not connected to your test environment. Other times it’s because you lost track of what you needed to change and are changing the wrong set of attributes. If you lose patience with yourself, you’ll never find the key that helps you solve your problem.
Very good post Allan; you’ve hit the nail on the head. Now if we can only keep the CGI out of our code, we’ll be doing fine. 😀
Alan Pringle
Sarah and I had the been-there-done-that reaction to your line, “Sometimes this is because you’ve forgotten that you’re actually changing the wrong piece of code in the plugin that is not connected to your test environment.” Have you been spying on us?
P.S. If CGI in DITA code will make me perpetually 10 years younger and give me six-pack abs, I’m all for it, Julio!
Mark Baker
I have to ask, though, why you should choose to use a system that requires superpowers to operate successfully. Just saying…
Alan Pringle
*Any* system is going to require some degree of superpowers–even off-the-shelf software has to be configured.
Mark Baker
Alan, I disagree. A good system should only require ordinary human powers. Unfortunately, tech comm has not been blessed with an abundance of such tools. We seem to have accepted that our tools are going to be difficult, flaky, and time consuming to use. It does not have to be that way.
Leigh White
Mark–that’s a key question. Every team has “the guy” (or gal)–the one who has assumed the responsibility of digging deeper into the tool or technology, setting things up, answering questions, and generally keeping the system humming along, whether that system be Word, Frame, Flare, RoboHelp, a database, a CMS, whatever. I call that person the “(wo)man behind the curtain.” It just so happens that DITA currently requires a little more magic because the tools that overlay it are in earlier stages of evolution. You can chose to use a stripped-down version of DITA for simplicity’s sake, and let the existing tools lead you along, or you can do the deep dive for maximum flexibility and customization, and I suppose that’s true of any tool. You can use Frame’s OOB templates–easy–or you can roll your own–harder (and sometimes really hard, depending on what you want to do). That said, I fully understand groups’ reluctance to adopt DITA if they don’t feel they have “that guy” on their team and can’t pay an outside resource. It’s actually a wise decision on their parts.
Mark Baker
Leigh, I think we have to stop letting vendors and system designers off the hook with the notion that the problem is that the tools are not yet mature. That’s not the problem. The problem is that the architecture is fundamentally broken, which is why it requires super powers to make things work.
If we started with a good architectural foundation we would not have to struggle through multiple decades of tool “immaturity”.
Leigh White
I agree with you in principle, but I’m not sure it’s realistic. No matter how well a system/tool is designed to do what it originally did, things change. It’s not financially feasible, either for vendors or tech groups, to completely trade out tool sets every other year to get the “new shiny.” And even if we do a solid needs analysis now and pick the ideal tools, there’s no guarantee they will still be ideal in 3 or 5 years. So we make the best decisions now based on what we know. If we’re smart, we pick something that’s flexible and extensible and doesn’t leave us dependent on the vendor deciding our ask is important enough to put on the roadmap. Something that we can configure at will to our own needs. Something like, uhm, XML 🙂
Mark Baker
That is exactly where I think the problem lies. Most of the tools we use were designed ad hoc to solve a particular immediate problem and then built out over the years to cover more and more things, but in an increasingly ugly and inefficient way. What we need are tools that are built on a flexible architecture from the beginning so that they don’t need to be rearchitected every time the wind changes.
Sarah O'Keefe
We have very little control over what the tool vendors choose to produce. We go to work with the tools we have, not the tools we want. (Many apologies for quoting THAT person.)
The argument that the tools should be better is always going to be true, but we need to get the work done NOW.
Mark Baker
Sarah, while I agree that the most pressing need is often to get the work done NOW, I actually think that DITA represents a marked change from the situation of being hostage to the vendors that we had with the standard DTP packages.
DITA was not the product of a tool vendor. It arose out of an in-house project at IBM that was later donated to and is now maintained by the community. In that respect I think it is a very healthy development for tech comm. The tech comm community is taking responsibility for designing and maintaining its own tools, and that is a very promising thing.
In some sense, you could say that DocBook was another case of the same thing, though it never caught on the way DITA has.
So I think tech comm has passed an important threshold with DITA. It had become a tool building culture rather than simply a tool using culture.
The software development community had been a tool building culture for a very long time. A great deal of the open source software movement is focused on development and infrastructure tools.
What we see in that space is that new tools are created over time to address the issues discovered with existing tools. Thus Git was developed to address issues with the design of tools like SVN.
I think it very reasonable to hope that as the downsides of the DITA architecture become more apparent with use (which happens to any tool), the tech comm community will develop a next generation tool that addresses those issues.
Leigh White
Circling back to Thomas Böttiger’s post for a sec, and Sarah and Alan’s responses to it…I absolute second (or third) that you can get completely professional output from the DITA-OT and commercial PDF renderers like Antenna House or (my choice) XEP. And you have so much more control over it…if you know how to exercise that control, that is. I’ve done things with XSL:FO that I could never have done with the Desktop Publishing and Document Processing Applications We Will Not Name. Fodder for another post for sure!
Alan Pringle
In the past six months, I have completed quick production passes on the PDF files for two Scriptorium Press books: one came out of our custom DITA OT PDF plugin paired with Antenna House, and the other through A Document Processing Application I Will Not Name™. I’ll let you guess which process produced more reliable and predictable results.
Bart Brigé
The DITA superhero’s kryptonite: perfect DITA topics that are perfectly useless. It should always be about the quality, the added value of the content, not adhering to the rules of a self-imposed system. So in addition to thinking and working like a programmer, I’d say: thinking and working like a first time user. But quality is hard to quantify of course…