We have product

Indeed. We have produced several documents using DITA. The issues with our CMS and editing tool continue to give us difficulties but we can see a horizon now.
Lesson: It's almost impossible to change your tool set without running into lots of problems. That's why there are consultants out there. They hold your hand and walk you through the thickets and get you to the other side. This is the consultants as scouts model.
We needed to shift because our workload is increasing. Unfortunately, we were not able to make the shift before our workload increased. We have learned some things and are being able to fix some problems ourselves. We're hanging in until some additional help is available. Instead of scouts, we're hiring helicopters to lift us out of the danger zone.

Dreaming

There is no way to start over; there never really is. But, that said, we're hopefully past the part of the slope that broke our spirits and nearly took our projects down with it. There are days when your sense that things are going to work out is so fragile that you lose hope and hope is the concept you need most during those times.

We're not all the way there, but here's where we are:

1. We've converted as much legacy content as is viable. Since the DITA-based content is for use with our forward-moving product lines, we don't need to convert every document we've ever written, just the best. We're down to recreating some content, tables in particular, that our conversion process just didn't handle.


2. We've moved almost all of our converted content into the new document management system (docbase). This process was horrible. First, we couldn't just port our converted content back into the old docbase because the version of the software we were using was so outdated, we couldn't connect our newer, as yet nonexistant, editing tools. So, while we nervously worked outside of the safety of the docbase our tools specialist, who has since gone off to do more satisfying things with her hands, worked on getting the hardware and software requests through the labyrinth purchase process and then the equally arcane IT request process (this is a big company and we are a small life-boat sized component operating in a sea of regulations and requirements that have little or nothing to do with our actual product line... and then we have another vast ocean of regulations and requirements that do have everything to do with our actual product line). Then, moments after everything is installed and our import process is 80% debugged, our tools person happily decamped. I'm proud of her, off doing less stressful things.


3. Okay, so most of our stuff is in the docbase but the process is still broken. Our tools can do part of the job but not all. So, we store our section maps in the docbase, export them and their child topics (and their child images), and build our document supermap. It almost works through about seven iterations. Finally, just as I'm unsnapping online, my coworker manages to create a Help file that links and does not sink.


4. Now, we have most of the content (there is still one large set of topics outside of the docbase and they need to move in) in the docbase and we can create a supermap in the docbase linking the sections into a manual; and we can export the supermap and get all the section maps, topics, and images (we think, at least in the small test we did, it worked). And, we can organize our content so that we continue to use the same, familiar cabinet and folder structure for the supermaps. The big difference now is that all our topics are in a shared location (organized for human viewing). The docbase lets us move topics and images from location to location, if in the coming months we reorganize our drawers, without losing the valuable connections we've built into the maps and supermaps. Whew.


5. We've updated our style guide. There are a number of sections that have parallel content, non-structured documents and DITA documents, describing, for example, which styles/elements are used for what and in the case of DITA content, the attribute settings.


6. Our translation company wrote our XSLT. We've test-driven it and used it in production (but now with the supermap in the docbase our delivery mechanism is about to change).

Live, from Bothell, it's DITA.

Somewhen a robot is doing my job

This past week has been challenging. We've spiralled into freaking out as our deadlines loom and we encounter one technical roadblock after another.

Land Mines in Action

In the past, we had a team of two people who implemented all our templates. They defined, designed, and delivered templates that reliably produced the CHM and PDF files that are the mainstay of our manual production. The teamwork and expertise is just not there for the transition to XML and DITA.
We have contractors converting our templates into XSLT. They're contractors. They aren't here, they aren't even in the same time zone, and the speed of communication is nowhere near light. We ask for stuff and we don't really get feedback until the the contractor deigns to deliver a revision of the XSLT and we get to see, for the first time, what it is they think we asked for. We tell a project lead on the contractor side what we want, that person assigns someone else, and that person may or may call or write to talk to us. We gave them our templates, we gave them sample documents, we worked with them through a pilot project (that they ended up cobbling together so we could ship on time) and a year later we still don't have XSLT that we can use without problems.
Going to work, these days, feels a lot like skinny dipping with piranha.

Global Warming

I'm not sure we could have pulled this off without the whole team. We provide enough viewpoints and collaboration to pull rabbits out of thin air.
We are a fairly robust team. This is the largest, most organized, and well-meshed teams I have ever worked with. There are no stars. There are no super-heroes. There are a number of people who respect each other and who have great work ethics.
All that said, we work in a corporation. The bottom line for the corporation produce more saleable product without increasing development costs; in fact, produce more and cost less, overall.
Thus, DITA for our user manuals. If this doesn't work, we're in big trouble because we can't do what we're about to be assigned to do unless there is a better way than what we had been doing and what we had been doing was top notch.
I don't know that DITA, as it is delivered today, would work for a smaller shop. I'm not sure about the ROI. For us, the ROI is going to be huge, even if it is only a tenth of what the promoters promise.
Today, I'm writing about a new feature that will be used on at least two of our products this year. I'll write the conceptual information and the instructions for use for one product. If the second product needs instructions, another writer will handle that. We'll have one conceptual topic used in two products. That's half the writing time, half the translation time (and cost), and half the review/validation requirement.
Next week, I'm writing about a series of features that are being created for one product that will then percolate through another seven products in the next year or two. Wow. Since the concepts will remain the same, and eventually the interfaces will merge (in this one feature set), that's eight for the price of one.

Psychic Faire

So, no, a robot won't be doing my job any time soon, but I miss the days when the template-driven process was mature, stable, and reliable. Some day we'll have that again. It's incredibly difficult to be a newbie again.