Sunday, March 23, 2014

DITA in times of contraction

When Pubs managers decide to move their doc content to DITA, all they see is the savings. It's ROI, ROI, ROI. "You have to spend to save," they argue, and they often start spending hundreds of thousands of dollars on software purchases, training, and non-writing personnel. All that's fine when a company is growing and has loads of cash, but what risks are Pubs managers exposing themselves to if the company hits bad times?

As I have argued before, in many cases DITA doesn't so much save money as redistribute it. Where before you spent the lion's share of your doc budget on salaries for writers, now you're spending the most money on tools developers, information architects, editors, and software.

I'll give you an example: I once worked in a DITA shop where a team of 11 writers was overseen by a manager, three team leads, three editors, and two information architects; and it was supported by nearly a dozen tools developers. There were almost twice as many non-writers working on the documentation as writers (and yet writers had to fill out complicated forms for the editors, as well as project-manage the localization of their docs). The CMS was enormously expensive, and then the CMS vendor end-of-lifed our database so we had to spend a pant-load on a new one, including two years of research, planning, tools redevelopment, migrating, and tweaking the migration.

In a DITA shop, teams become complexly interdependent. Much effort is expended on assimilating writers so that they give up their holistic approach to writing, and accept their role in a DITA production line that starts with information developers; relegates writers to the role of filling in content in designated, pre-typed topics; and ends with editors. As it was explained to me, the writer must learn to pass the baton. DITA proponents argue that writers who can't assimilate should be fired.

The CMS and publishing tools are enormously complex so that nothing can be published without the help of a large team of tools developers. In addition, the complex new processes and corresponding bureaucracy require training (and hence trainers) before new writers can become productive.

Now imagine that the company has a profit dip and needs to cut costs. Who and what is expendable?

Before you had a team of writers, and if the company got in trouble you could lay off some with minimal impact. But now, if you have to contract your Pubs department you're in a pickle. The information typing process relies on so many non-writers that it seems inevitable that when companies are in decline, a DITA shop is going to have to give up more writers than a non-DITA shop.

That fragile CMS doesn't run itself, and keeping it going requires expert skills: you're going to have to keep most of your tools developers unless you want to give up publishing documentation altogether. It's probably not possible to give up the expensive maintenance plan for the CMS, either.

Your complex processes are going to continue to require the trainers, team leads, information architects, and editors.

In short, you're left with an expensive behemoth that can't be easily dismantled... unless you decide to ditch DITA altogether and migrate to a simpler solution.

The risk of DITA is fine when there is real justification for adopting DITA: when there is real need for reuse, when translation savings can't be garnered by a simpler alternative like Docbook XML or Madcap Flare, when you absolutely need to enforce strict information typing on writers. The problem is that nearly all outfits that are adopting DITA do not have that real justification. They're wasting money on DITA, and that could get them into trouble when the cash stops flowing.

Helping developers write better API references

Several years ago I gave a presentation to developers at my company about how to write better API references. The goal was to help developers who produced public APIs to write code comments that would be more useful to the mobile app devs who used the APIs.

I started with a quote from senior management about the importance of the API references to the success of our products. At this point and throughout the presentation, I wanted it to be clear that I wasn't just some tech writer spouting off about how to do things: this initiative was important to development management. I constantly threw in quotes from development managers (using their names) to support what I was saying. (I couldn't go so far as to say there was an integrated initiative because there wasn't.)

Next, I sketched the current Pubs team initiatives to improve documentation for the mobile app devs: new web sites for doc delivery that made it more easy to find and use the content; new feedback mechanisms; research of what the app devs wanted; and developer outreach such as the presentation I was giving them.

On the subject of research, I described some recent work I had done. I had gone to a developer conference and conducted a focus group, as well as six round-table discussions; collected questionnaires; and done dozens of usability tests with developers. I had attended a hackathon where I interacted with participants, learning their frustrations and successes. I had also attended a Developer's Day where I talked to prospective app devs about their backgrounds and their interest in using our APIs.

My main take-away from that research, I explained, was that mobile app devs want development to be easy. One of my bullet points was, "They are looking for information that is complete, simple, easy to understand, quick to use, and easy to find." This may seem obvious, but most developers seem to assume that app devs don't want to be told too much - that they can figure it out. In my experience, all too many technical writers in development documentation make the same false assumption. What app devs say is: Spell everything out! Tell me how to do it! As I explained in my presentation, three-quarters of the app devs I talked to were working on multiple platforms, not just ours.

Next I shared some personas of mobile app devs. These were not personas that I had made up, but that I had got from senior development managers. (As I have argued before, I firmly believe that personas should be prescriptive rather than descriptive.)

Finally I got to the point where I could define what a public API reference is, and show some examples from our company. I criticized our current API refs: it was too difficult to create mobile apps with our APIs; app devs were complaining; we had acquired a reputation of not being developer-friendly; the API references were a major source of info for technical writers, so the rest of the documentation was suffering; we were getting too many support calls.

I showed an example of a really bad page from one of our API references and explained what was wrong with it. Then I showed them an example of a really good page and talked about why it was so useful to readers. That led into an interactive session of about 15 minutes where we looked at API references and discussed how to improve them. Although there were about 100 developers in the room, the discussion was lively and very positive.

The rest of the talk was guidelines to improve our processes going forward. I defined responsibilities:
  • API developers: Document all the elements of the API as comments in source code.
  • Tech writers: Review the API reference to help with wording, fix typos and grammar, and note missing content.
  • Both: Tech writers collaborate with developers to add content and examples.
I told them that when they started to write code comments for public APIs, they should ask themselves: What is it? When would this be useful or necessary? Why would app devs want to use it? How do they use it? I said the The API reference should explain: every class, method, parameter, etc; side-effects (what this code will affect and vice versa); and assumptions: always think of the customer. Imagine someone who is busy, doesn’t want to spend a lot of time figuring things out, hasn’t immersed themselves in our environment, just wants a quick answer.

After that I described some of the reasons our company had ended up with poor API references, providing a solution for each issue. For example, one solution was, "Ensure that the API reference is a deliverable. Make the API reference a product requirement. Add the API reference to the Definition of Done."

In the question period at the end, many of the developers provided even more ideas for how to make things better going forward. I ended with a quote: “Poorly documented code? Chances are the problem lies not in your programmers, but in your process.”