Manual writer

We're approaching a milestone in our first multi-participant DITA project. Our pilot project was a small team (me, an editor, and the multimedia specialist who converted my images). This project has three writers working in an entirely new way. We've always collaborated, but in what my manager calls a clone and own fashion. Now, we're relying on each other to provide the topics and section maps that fit into our manual map.
This has involved a number of hallway decisions. We meet each week with increasingly lengthy and detailed agendas. We've added new content to our style guide and we've written an in-house DITA user's guide. In a few weeks, we'll produce our first book written in this model. The book is an in-house review edition, but it has to have, pretty much, everything in place to be reviewed and approved. We have a fairly rigorous review process.
One of the issues that came up this week was image management. Not only do we have to come up with new standards and instructions for image capture (screen shots), but we have to figure out how to track what has been captured and what is still needed. There are images that we can reuse, just as we are reusing text. Our current standard discourages screen images that require translation (costly!), so our screen images can be shared, especially if they show something like an icon state that may be affected by more than one task.
The out-of-the-box transforms did not handle the step cross-references well, at all. When I inserted a cross-reference to another step, my output contained the entire step, not a number indicating which step I was referencing. (As in: Repeat steps Enter your password. through Select your profile entries..) Our XSL developers handled it much better. This had been an issue during the pilot phase, before we could test what the developers were doing, we were using the default transforms. In the pilot, I had to re-jig my instructions in a couple of places to deal with situations where one instruction was, essentially, repeat until done. So, I turned those into lead-ins for sub-steps (in the pilot, we're not having to do that for this manual, thank-you very much). So instead of:

1. Do the first thing.
2. Now do this.
3. Do this.
4. Okay, finish up by doing this.
5. Repeat steps 2 through 4 until you're done.

I created a wee monster that looks like this:

1. Do the first thing.
2. Repeat these things until you have everything you need:
1. Now do this.
2. Do this.
3. Okay, finish up by doing this.
   

While we're waiting for our new CMS implementation, we're working in a rather awkward modality (to us, who are used to simply checking a file out and getting all its children, finding everything available in one, simple location). We do have a shared file drive, but, there are limitations, in terms of access, for people working off-site (and each of us work off-site at least one day a week). So, we have a convoluted solution using the CMS that is in place and zipped sections. It's working, but we're really looking forward to the new CMS implementation (this is a long, complicated story).
Luckily, our current style has reduced our need for many of the elements in DITA. Our content is very lean. Our audience is expected to be knowledgeable, or at least trained. The use of our product is so broad, that we, essentially, end up saying here's what this button is for, here's how you get to this menu of options, or here's a list of the options for this bit of functionality.
Our steps, mostly, fit into the element. Our content can be parsed, fairly easily, into concept, reference, and task. We discourage in-line cross-references and encourage related topics links.
I can't imagine trying to re-engineer our content, any more than we have, and meeting our deadlines. The conversion process was incredibly labour intensive. Bringing in help got content out of the legacy format and into XML, but putting it back together was a combination jigsaw puzzle and scavenger hunt.
We're fortunate in so many ways. The greatest asset in this transition has been the composition of the team. We're an easy-going, hard working, and collaborative group. When there is a problem, we fix it as a team. We're not fond of change, we demand a good reason for change; but when we're given a good reason, we'll get behind it and pull. We're not as daffy as the developers upstairs, but then, we're not being asked to recreate the moon every few months.

# posted by Wanda @ 07:07