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.

# posted by Wanda @ 12:57