The True Costs of DITA Adoption

For anyone who disagrees with this post: please leave a comment or send me an email. If I am incorrect about something, I will modify the post so that I am not spreading misinformation. And I would love to have a dialog on the topic.

There are many articles that advise doc managers about how to calculate return on investment for potential DITA adoption. Most of these articles seem to be written by consultants who make money by helping companies set up DITA systems: they have a vested interest in making DITA look beneficial. Also, they tend to help out during the initial migration and might not be around when some of the costs kick in: they simply might not be aware. Finally, they might deal mostly with large companies where large expenditures do not seem excessive. For whatever reasons, the literature seems to be underestimating the true cost of moving to DITA.

There can be a lot of costs related to DITA adoption. Here are some that might affect you. (Different implementations will vary somewhat.)

Most of us know about the cost of a CMS, which can set you back over $250,000 (or might be a lot less). You can do without the CMS, but DITA is designed for use with a CMS and you need one to get the full benefits. But the CMS is just the start.

In the early stages of your migration to DITA, you will likely need to hire DITA specialists (the consultants I mention above) to help you plan and set up your system.

You'll likely need more inhouse tools developers, and you may need developers with different skills than you currently have. This is not just to set up the new publishing system and so on, but also to troubleshoot publishing problems, adapt to new browser versions, and address all the bugs and glitches. In my experience there are all sorts of problems that crop up with the relational database (CMS), and also with the ditamaps, formatting of outputs, and many other things. Part of the problem is that the DITA Open Toolkit is notoriously difficult (and could require extra expense for things like a rendering engine). Some of the tools designed to work with DITA are arguably not quite up to speed yet. Your tools developers will also spend a lot more time helping writers.

(If you don't move to a CMS, but use something like FrameMaker and WebWorks ePublisher, you may find that you have a lot more headaches in producing docs without much in the way of DITA benefits.)

You need extremely skilled information architects to create a reuse strategy, engage in typing exercises, and design and edit your ditamaps. This isn't a skill set that people currently in your organization can easily acquire. Even most information architects have trouble adequately mapping topics. For a discussion of the sorts of challenges they'll face, see this series of posts; the moral is: if you don't have skilled architects working on your system, you may end up with Frankenbooks that are not particularly useful for your readers. I raise some additional topic reuse problems in an earlier post: link.

You'll need to spend significant time developing new processes, policies, and internal instruction manuals.

Your team will have to undergo intensive training. In coming years, new writers you hire will also need training. I have found that writers can move to Docbook XML with very little training, but DITA requires a great deal of training, not just for the CMS, but also to learn how to use ditamaps, reltables, and so on.

The migration of content will likely be quite time consuming, with manual work required to correct tagging that doesn't convert automatically, mapping, and a complete indepth edit.

Your writers will need to spend more time on non-writing activities. This can greatly reduce their productivity. Working with a relational database, especially an opaque one like a CMS, is much more time consuming than checking files out of a version control system. Creating reltables is a lot more work than adding links. Coordinating topics is a lot more work than designing and writing a standalone deliverable. Plus, there is a lot more bureaucracy associated with DITA workflows.

With most DITA implementations, topics exist in a workflow that only starts with the writer. You'll probably need more editors and more software.

You'll also probably need more supervisors. The DITA literature emphasizes the importance of assimilating writers to the new regime and then monitoring their attitudes. Pre-DITA, writers were project managers for their own content; with DITA they have to learn to hand that responsibility off to others.

There are some organizations, such as ones that have to cope with hundreds of versions of a hardware product, that have a clear ROI for DITA. But many (most?) organizations could find that DITA doesn't so much save money as redistribute money. Where before you spent the lion's share of your doc budget on salaries for writers, now writer salaries will be a much smaller proportion of your budget. In many cases, companies could find themselves facing higher costs than pre-adoption: they will never see return on their investment. And given the complexities of using DITA, ongoing hassles and escalating costs, some companies are going to find themselves having to ditch DITA and go through an expensive migration to another system.

Introducing "Information Designers Waterloo"

Mark Pepper and I created a LinkedIn group today: Information Designers Waterloo.

It's a local group for technical writers, information architects, editors, instructional designers, doc managers, doc tools developers, and all else who are interested in discussing tech writing issues, networking, job info, and... whatever this turns into.

I'm hoping we can have some lively discussions and some local meet-ups.

So if you're in the Waterloo area and if you're in the biz, please join up!

Think ecosystem

(This is part of my series on what I learned at the Fluxible conference over the weekend.)

Michal Levin of Google talked about the growing interactivity of devices, and what that means for app development. She said...

In our new era of connectivity, we'll increasingly be designing apps not for a phone or a PC, but for an ecosystem of device types (phone, tablet, PC, TV and... who knows). Here are three new design models:

• Consistent design - For apps like Trulia, which have versions for the PC, tablet and phone. All should have a similar IA, navigation model, and look-and-feel.
  
• Complementary design - For apps where devices control or influence each other. For example, with KC Dashboard you use a phone to throw darts at a dart board on a tablet. Some other examples interact with a TV: Real Racing 2, Slingbox, Heinekin Star Player.
  
• Continuous design - When you start a process on one device and then move to others. For example, All Recipes starts on a web site (probably viewed on a PC) where users choose recipes for a meal. The web site downloads a shopping list to a phone, and downloads recipe instructions to a tablet.

The ecosystem approach is just getting started, but we should all be aware of it and plan for it. For example:

• If you are creating an app for a single device type, you should consider ways to make it scalable and flexible for the future.
  
• You may need to use cloud computing for the data sync required by multi-device coordination.
  
• Some companies should consider changing their corporate structure so that development for phones, tablets and PCs is not done in separate divisions.
  
• The ecosystem concept will expand as computer chips become ubiquitous in home appliances; as their use in cars improves; etc.

In his closing keynote, Dan Gardenfors of TAT picked up on Michal's idea of future extensions to our online world. He envisioned a world of public computing where screens are everywhere (on buildings, bus shelters, bus windows, etc). One of the uses of these public screens could be to have the ability to screen whatever we are watching on our phone. Other uses will be advertising and public information. He suggested we start thinking in terms of a mobile computing platform rather than a platform for mobile devices.

The future of IA... or what to do with all that content

(This is part of my series on what I learned at the Fluxible conference over the weekend.)

Karl Fast, a prof at Kent State, talked about the huge load of information that is available online and how we can cope with it. He doesn't have a solution, but suggested themes that information architects might pursue towards finding a solution. He said...

Our current ways for processing all this information are:

Intentional structure, such as a library or folders
Algorithms plus computation (the Google approach)
Loosely coordinated group actions (the Wikipedia approach)

Information is cheap but understanding is expensive - and we have not figured it out. IA is about understanding the world as it may be, and a fundamentally new way of processing information is needed but might not happen for a long time. In working towards that new understanding, he has come up with some themes that might prove fruitful. They seek to understand how people work with content. They all fit into the idea of cognition as extension. For example, when we do a jigsaw puzzle we look at the puzzle, using just our brain, but we also move the pieces with our hands. We combine pragmatic action and epistemic action.

These are the themes he thinks might be fruitful in moving to a better way to process content:

Deep interaction - He argues that our mental model is wrong: we think cognition is all in the brain, but it's really part brain, part external: gestures, inflection, content artefacts, people, devices, etc. (When we do usability testing we usually ignore a lot of really important stuff like gestures.) Scientists have discovered that we don't just use our brains to think: thinking is a mind-body integration. For example, gestures are so important that we don't think as clearly if we don't gesture. Another example: this study of Tetris users concluded that thinking is not all in the brain.

Coordination/orchestration - We coordinate a variety of online devices, books, a whole bunch of things. It's not as simple as processing one thing. We have multiple PCs, tablets, smartphones, etc., and also have non-electronic content to coordinate. To figure out how to process the vast new amount of info we face, we should think of PHINGS: Physical, haptic, interactive and information-rich, networked and next-generation, stuff on surfaces. These refer to:

Physical: not just the brain, but also the body and physical things
Haptic: non-verbal communication
Interactive and information-rich
Networked and next-generation
Stuff on surfaces: on screens or paper

Mess - We tend to treat mess as an a bad thing to be avoided, but mess is necessary and should be worked into our theory. "Mess is the soul of creativity." Messy desks, messy desktops, messy bookshelves. Mess is a fundamental part of reality and we need a way of describing it. The idea of mess is completely tied up in the idea of deep interaction and PHINGS. Mess reflects our reality.

While talking about mess, Fast told an anecdote about Steve Jobs. Jobs liked to popularize a myth that he lived a stripped-down, simple life, and played up a time when he had no living room furniture... but this is what his home office looked like:

All this is a bit difficult to comprehend, especially as it applies to a way to process online content. I was fascinated but not exactly led to enlightenment. I am not sure I have captured his meaning perfectly, but I'm going to keep Karl Fast on my watch list. You can find his published papers here: Medeley Profiles.

Update: Karl Fast recently left Kent State to become an information architect at Normative Design.

Apps suck

(I was at a user experience conference called Fluxible over the weekend. This post describes one of the talks I attended, and is part of a series.)

James Wu, lead designer for tablets at Kobo, gave a talk called "Rethinking tablet UX". His central insight is that users are interested in content, not apps. He said...

Technology sucks for most people. Unlike most of us at Fluxible, most people don't want to know, understand or learn the techie features of their devices. They don't like having their main tablet navigation be small impersonal icons that represent all their apps. They hate it that their content is stored within apps. They're interested in content: in their movies, music, pictures, books.

This is what people want to do with their tablet:

• Find content
  
• Organize content
  
• Consume content

At Kobo, James has been involved in the development of a new tablet look called Tapestries, which is a way to let users focus on content. He calls this "organic curation". Users can create a tapestry, multiple tapestries, and sub-tapestries. The full sample he showed us was a page a woman might create to plan her wedding. It had lots of big pictures.
- - -
I wish he had also shown us something more meaty, like a tapestry I might use to store research on something.

In fact, for my personal use, I'm not convinced that Tapestries is the best application of this idea. But the idea is a winner. I hate apps. I hate having four screens of the stupid things on my phone. I hate having to remember which eReader has which books. I think content-centric UI design is/should be the next wave.

Case study: LinkedIn web site fails?

It's astounding how an important, established web site like LinkedIn could have such utterly crap design on its Groups page. Using "More" as a category is always an unfortunate design decision (although sometimes necessary), but on this page, LinkedIn uses the "More" category three times (as marked in red).

I belong to a lot of LinkedIn groups, and I only ever click one setting on the whole page (other than group links). That option is in the second "More" listing and it's "Settings"...

... and the only thing I ever do there is stop LinkedIn from its default behavior of sending me endless emails about discussions in the group.

The kicker: the third "More" (in this view) doesn't even do anything.

Musing about topic reuse

I first started writing in a dot command language called Script. Later I used TROFF and then LaTeX. But eventually the WYSIWYG editor was born (I had mixed feelings about it at first), desk top publishing applications and laser printers appeared, and Macs hit the market - and typefaces hit the world with a bang.

Tech writers, wanting to show off what they could do, started using typefaces like there was no tomorrow. Some manuals were so busy that it seemed like every word was italic, bold, colored, or in a different font altogether. They were hard to read.

(We still overdo typefaces to a certain extent. I would like to use bold only to designate words that I want to "pop" off the page, and not for UI controls and so on... but that appears to be a battle I have lost.)

Nowadays I wonder if topic reuse is a bit like those heady days of typefaces. When we say, "my doc set has topic reuse of 30%," that doesn't mean "my doc set needs to have topic reuse of 30%." There is a sense of "Topic Reuse Good, No Topic Reuse Bad." There is a need to justify spending a lot of money for tools like CMSs that facilitate topic reuse.

I have also noticed a tendency among some writers to pad out their deliverables with other people's topics when it isn't really helping the reader. When working in large writing departments, I have found my topics in odd places where a link would be more useful. In one instance I took a deliverable that was 50 pages in PDF form and deleted the reused topics, creating a much more focused, useful doc that fit on one HTML page. The reused topics in that example were actually harmful because they were pulled out of context. I know, topic-based writing isn't supposed to have context, but in many cases it does, especially with complex subjects.

The problem is that writers are given latitude - and are even pressured - to reuse topics when there is no clearly defined reuse strategy. In fact, I have never seen a well-articulated content reuse strategy. You see descriptions of the mechanics of reuse, like this one or this one, but they don't provide guidance on why to reuse topics and which topics to reuse.

Sometimes topic reuse makes no sense, like a doc set I once saw that repeated a large set of introductory topics at the beginning of every deliverable, which to my mind just clogged up the user experience. Even worse, a decision was made to include the topics in the HTML and not the PDF - the reasoning being that the topics weren't really needed and would add to printing costs - which confused readers about whether the two outputs were two different sets of content.

Sometimes topic reuse strategies are ill-considered, such as trying to use doc topics in training material. Docs and training require such different styles of writing that that can result in really bad output, and only seems to make sense when cost-saving requires highly compromised training materials. (Which, in that case, is fine, as tech writing is necessarily all about doing the best we can with available resources.)

Sometimes topic reuse becomes a sort of mania, an end-in-itself. I once saw a DITA topic that single-sourced a table that described fields in a screenshot. There were three versions of the screenshot, each completely different UI screens, each marked with attributes for different products. In the table, there were two or three rows that were not conditionalized. There were about a dozen other rows that each appeared three times, marked with attributes for the three different products. Updating the table was a nightmare, as you might imagine.

This is not to say that topic reuse is not useful. Anyone who has had to modify the same text in two places knows how important topic reuse is. But I have never documented hardware, so I have never worked on a doc set that required a lot of topic reuse. Consequently, approaches like this one, in a department where 48 writers produce 14,000 publications, were not even remotely applicable. (I have worked in departments with that many writers, but never with even one percent of that many publications. It is my contention that that is not the norm.)

My preferred approach would be to reuse topics when previously you would have cut and pasted the content, and otherwise a writer would be required to make a case for reusing a topic. My reasoning is that we must never force the reader to read anything more than they need to read. (Unfortunately, minimalism is often thought of in terms of our convenience and costs rather than in terms of reader usability, as it should be.)

We are in danger of reusing too much because reuse is easy and because there are non-reader incentives to reuse, as described above. The problem with my approach is that it could keep the stats on reuse low, which wouldn't help with proving ROI for the CMS or other tools that were bought with reuse as a justification. But it would help avoid a tendency to go hog-wild and reuse when it's detrimental to readers.