Tuesday, July 31, 2012

Case study: DITA topic architecture

This post is part of a series of posts that question some of the claims made about the benefits of DITA adoption.

(Note: DITA uses the word "topic" to refer to a reusable module of content. Out in the rest of the world the word topic tends to refer to an HTML page or a section of a PDF. This may be seen as an infuriating oversight, but I suspect it's actually deliberate. For a while I tried replacing DITA "topic" with "reusable module of content" but I have given up and now just use the one word to mean multiple things.)

I started with DITA several years ago when I got a job in a large doc team that had been using DITA for a while. I inherited a few deliverables and was appalled at the way the content was broken up into concept, task and code sample topics. We optimized for HTML output and there were too many brief HTML pages that users had to click through. Even for a simple idea that could have been covered in one paragraph, these docs would have three topics. For example, a description of how to stop the server would have a concept, task and sample topic, each appearing on separate HTML pages.

My audience was developers. I did quite a lot of usability testing with them and found they were furious about the documentation. They hated having to click through multiple tiny pages. They hated the minimalism and choppiness. They described the docs as unfriendly, officious, insulting and unhelpful.

Conflict in the Pink Ghetto

When I was a child I had a recurring nightmare about pink and black. It always started with a visual of pink fluffy clouds, not dissimilar from cotton candy, and it gave me a feeling of intense well-being. Then a viscous black ooze would start to infiltrate, a little at first and then growing until the pink was obliterated, leaving me unsettled and frightened.

Nowadays I am far, far from childhood and I work in the field of technical writing. I was a tech writer early in my career and chose to return to it in the 90s, after deciding that I am best suited to cerebral, creative and mostly solitary work.

The problem was that, at least back then, technical writing was a classic pink ghetto occupation - female dominated, not highly regarded by other workers, and not easy to move up out of - and that this caused it to be a rather hostile environment.

Case in point. When I returned to tech writing I worked in a department that had about 50 writers. We produced excellent documentation on complex, technically challenging topics. The writers, who were mostly female, were all extremely bright. Almost everyone had a university degree in a math or science followed by a two-year tech writing diploma.

It was a vicious place. Writers regularly yelled at each other, threatened physical harm, and lodged harassment complaints against each other. The turnover in writers was staggering.

My next job had a mix of men and women. It was to my mind an excellent place to work - fascinating work, great pay, private offices, good treatment - but most of the other writers hated their jobs. One writer refused to implement tech reviews because he said it damaged his self-esteem. Two writers worked less than half the time they were supposed to. Another writer, the manager and I carried the load for a department of seven. It has been my experience that slackers can become paranoid and nasty, especially when they're caught in a web of lies to hide their lack of productivity, and that described this group.

The bad behavior of tech writers is a well known phenomenon, or at least it was up to five or ten years ago. I have heard the argument that writers behave badly because they're lesser-paid and lesser-respected members of R&D departments that are otherwise staffed by brainy, egotistical developers. In this argument, it's a fight for the top of the bottom rung.

However, there are other bottom-rung departments in R&D divisions (QA, testing, build) and I never saw them exist in a state of constant nastiness. Likewise, there are other female-dominated professions (marketing, PR, EAs) that don't seem to have these problems. Tech writing is perhaps different in that it is by nature submissive; we writers are always asking other people to give us information, and then always getting reviews that tell us what to change. That position rankles some people, and maybe it causes aggression.

Over time the tech writing profession managed to reinvent itself. It found a way to earn the respect it always deserved and needed. Job titles changed. Some people went the techy route ("Information Product Developer") and some the usability route ("User Advocate"). Previously, the cherished skills included layout design, grammar and clear writing. Now it has become more important to be skilled at complicated tools and to know markup and scripting languages.

As with many good things, the golden age of tech writing as a professional, respected profession seems to have lasted but a nanosecond. It is being replaced in many organizations by the mindset that came along with DITA.

DITA is a specification for creating documentation in XML, but has brought with it a whole new approach to tech writing. It's difficult not to resort to mixed metaphors here. In the DITA world, writers are treated like children and are cogs in a wheel. Previously a team of writers worked together to write with one voice. With DITA, writers follow strict guidelines and templates to produce small units of content. There is a tendency in DITA processes (enforced by CMSs and other tools) to remove responsibility for the final product from the writer. Workflows are imposed in which the writer creates the first draft, but then hands it off to editors and team leads who make changes and give approvals. Everything is dictated by the workflow - everything but quality, user focus and a process of continual improvement, which somehow got forgotten.

Tech writing changed with DITA because DITA is a top-down orthodoxy. The problem may be that DITA was influenced too much by consultants, academics and tools vendors, people with personal agendas and too great a distance from real world tech writing. The problem may be that it was developed for hardware documentation (doc sets that require a great deal of content reuse) and then was applied out of context. I think the mindset is gaining a foothold because it's a continuation of the drive to make tech writing seem more serious and difficult. (We develop reusable modules, just like object-oriented programming!) Paradoxically, the mindset is hindering writers from doing their best work.

DITA has also resulted in mind-blowingly expensive budgets for tech writing departments. DITA is optimized for working with a CMS, a relational database that can set you back over $100K. XML authoring has no off-the-shelf solution, and requires docs tools teams to troubleshoot, maintain the system and upgrade. Pre-DITA you could assign each writer some subject areas and leave them to it. With the new modular style, many organizations feel the need for more architects, editors and team leads to oversee the content production process. In some organizations, doc departments have a ratio of less than 2:1 of writers to support/supervisory staff. And many organizations don't achieve the degree of content reuse that justifies the extra cost.

None of the trends in tech writing occurred at all places simultaneously or for the same reasons, and some organizations will skip them altogether. But there seems to be a pulse of positive and negative influences, with a steady movement of tech writers trying to look more like developers. And in the predominant dialog of the last decade, there is far too little focus on the reader.