Manual writer

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.

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.

Labels: dita, standardized processes, templates, transition

We have a number of products (ultrasound systems) that share a basic document structure and include super- and sub-sets of a range of features. It made sense to us that we would have maps that contain the standard document sections and each map topicref element is tagged to indicate the products that support the feature discussed (or in the case of tasks, the specific set of steps in the procedure). If our product was a car it would be akin to having standard topics that describe what the various parts of the car are and more variance in the topics that describe where to find the parts and how to use the car.
In some cases, different sections of the manual include the same topic. If, for example, the car manual had a discussion about tires and the author responsible for the section that covers changing the tires wrote it, but the author responsible for the section that covers handling the car in various weather conditions wanted to use it, the resulting book would display the topic in the two locations but references to the topic would always go to the first pointer. So, a topic in the weather conditions section that included a link to the tire discussion would drop the user into the middle of the section that covers changing the tires. Contextually incorrect even thought the content of the topic is correct.
Any related topic links in the topic would appear to point to changing the tires, not handling the car in snow (or other extreme weather).
To get the output to point to the correct iteration of the topic, the contextually correct iteration, you can use the copy-to attribute of the topicref element.
When creating your map, you can set the attributes (and depending on the tool you're using, you may have to switch over to plain text editing to do this) for the product and the copy-to. The copy-to attributes, as I understand it, creates a virtual copy of the topic with a unique name. Using the car example above, that would look like this:
<topicref href="About_Tires.xml" copy-to="About_Tires_Service.xml"/>
<topicref href="About_Tires.xml" copy-to="About_Tires_Handling.xml"/>
To create a link to the version used in the car maintenance section, you use About_Tires_Service.xml in your reference. That brings your reader the contextually correct occurrence of the topic. To create a link to the version of the tire discussion used in the section on driving, you use the About_Tires_Handling.xml.