Manual writer

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

I'm a reasonably intelligent person. There are some things I can understand on a conceptual level that I cannot make work on the concrete level, and vise verse. My coordination is great, unless I'm thinking about it. The day I put my lawn mower together was a magnificent day. As far as I was concerned, I'd climbed Mount Olympus and won a wrestling match with Hercules all in one fell swoop. My vocabulary is pretty good, but there are days when polysyllabic explanations leave me muddled and frustrated; being frustrated muddles me even more. Then, when I find out that there is a perfectly good, simple explanation for the concept, I stomp. I get pissed when I'm outsmarted by words. It drives me nuts.
I'm working on two, related, projects right now. In one, I'm learning how to use XSL to play with XML documents. When I see the solutions, I can see, exactly, how it works, but I can't get there on my own. My second project involves DITA (Darwin Information Typing Architecture) and there are three types of conversations about DITA that all revolve around how to do something with the structure of DITA. Some of the conversation is easy, authoring issues - some of the conversations are technical, dealing with XSL or the rendering engines - some are just beyond me and I have no idea what they're talking about. My three buckets. One I can follow, and often get ideas from, one that I can peer vaguely into and get the gist of, one I am left wondering just what the writer is saying and what they're saying it about.
I would sigh, in fact I did, but that is not something that really works in this medium.
If the medium is the message, I'm wondering what I'm missing. The whole idea of simplicity, in this case I'm exchanging my reader-facing simplicity for my creator-facing simplicity. I'm balancing a huge technical weight hoping that I will be delivering, to my reader, a clear, focused result. Something that will make their experience simpler.
I just wish it didn't leave me feeling like I've just jumped off a bridge because someone else told me it would be a good idea.

Labels: authoring, dita, hapless, XSL

One of the things that was keeping me awake last night (I really should have just come downstairs and worked it through then, instead of waiting all this time...) is the idea of measuring quality in documentation. Mentally reviewing the judging sheets from yesterday's competition, I starting thinking about the combination of those elements and DITA authoring.
One of the most serious, for us, drawbacks of the transition to DITA is the loss of our call-outs in our images. Since we translate content into a couple of dozen languages, the call-outs have to be accessible to the translators. The cost of having translators, or graphics specialists, recreate embedded call-outs is ridiculous and cancels out the prospective savings that the topic-level management, inherent in DITA, promises. There are some possible solutions out there, but for our skill level, they're not ready for prime time. There's that issue with XSLT again.
Indexing, in XMetal at least, is easier for me than in other products where the contents of the index entries are invisible. What I miss is the ability to collate the index markers (like Ixgen) and edit them en masse, as it were. I expect that in another 5 years DITA tools will be as full-featured as most DTP packages are now. As with all tools and methods, there are trade-offs.
Learning XML, whether it's DITA or not, shows me how integrated presentation and content had become. With fine-tuned tools, the presentation aspect does not take up the bulk of time. At work, we have processes in place that have meant that I've been able to concentrate on content. We have iron-clad templates that are maintained and sustained in concert with our translation company. Those rules mean that our output is consistent, worry-free, and fast. Drop a document into the output engine, for online help or Portable Document Format (PDF) and come back later to pick up the final output file.
The difference is, we could see what our output would look like before we dropped it into the black box (well, black box to the writers, but we have in-house experts who knew how to manipulate the processing); our editors could ensure that our style rules about widow and orphan content were handled in the source files. But, with DITA, we drop our content into the black box and we all stand around anxiously awaiting the result. None of us know how to make the processing work. None of us know how to tweak a paragraph or table to ensure the formatting is beautiful in the output. This has probably been the most frustrating part of our transition.
So much for judging by presentation.
Well, instead of muttering on about this I should be doing my XSL homework.

Labels: dita, formatting, indexing, processing output, XSL

When we selected DITA as our DTD/application, we did so, in part, because our current styles are a close match for the DITA structure. There are some minor variations but we chose to shave off the stuff that didn't fit and consider specializing the DTD later, when we had a grip on what DITA is and what using it does to our process.
Because our products are part of a family, each generation building on features, functionality, and options developed and delivered in early generations, we are accustomed to borrowing from existing content and reshaping to fit the new product and any changes to our styles.
We also have a content guideline that provides a structure overview. This document does not delve into the structure in the same way a DTD does; the structure overview says, essentially, the following information, in the following order, appears in this kind of document. This structure varies, somewhat, with each product release; its purpose is to identify the full scope of our most comprehensive documents.
You can see that we're a very organized group of people. We're pretty cautious and we're definitely turtles in terms of change. Faced with the theory of the transition to DITA we felt some apprehension. We attended multiple seminars, webinars, and training classes. Everyone talked about DITA at a very high level; we could talk that talk, without ever having authored a DITA topic. We were hungry for details.
Eventually, we had to start. During the planning phase, we identified some elements that would allow us to select the best starting place, topic by topic, for the new DITA content. We developed these guidelines:

• If the content is already converted, use it (or at least start with it).


• Otherwise, choose content based on the following attributes:
  
  
  
  • Which topic is the most recent?
  
  
  • Which topic most closely follows current styles, conventions, and terminology? Something that is somewhat implied in the first attribute... more recently content is authored the more likely it is that it follows the current styles.
  
  
  • Which topic requires the least amount of rework? This is simply a variation on the earlier attributes.
  
  
  
  

What it comes down to is this: writers pick the version of the topic that fits the situation. In some cases, we're taking topics from older manuals and updating the style because the flavor of the features is more like those earlier products. In other cases, we're taking topics from the most recent product release and modifying the content because the tone and depth is more appropriate even though the implementation of the feature is different.
We are taking advantage of the transition to set a new gold standard for our content. The entire team meets weekly. The team includes production people, writers, editors, and managers; all these people have a stake in the outcome. It's in meetings of this group that goals, like the topic selection guidelines, come out through discussion and exploration of ideas and information received.
The experience of converting a simple set of product manuals and producing output gave us a road map for discussion issues. As each phase of our workflow came and went we discovered issues we could not have forseen. One of the other outcomes of these meetings has to do with handling graphics. That issue is unresolved. We managed, with the pilot project, to duck tape something together (to meet a deadline rather than actually resolve the issue) and as our new product deadlines can be seen on the near horizon, we're about to tackle the whole image issue, for real. I think I may have to fall down and take a nap.

Labels: conversion, dita, styles

Because our products share features, we are changing how we assign our development effort.
Previously, as each product was released, an individual writer was given the responsibility of pulling together the information required to create or update the user documentation. In this scenario, writers become generalists and researchers. The research may lead them to borrowing content from other products and tweak it to fit.
The content was stored in section files that were pulled together into a book. When we sent content to translation, they had to process the entire section file to find the changes.
When translators got this content, they may end up having to treat any "cloned and owned" content as new, thereby losing any savings in the reuse.
Our DITA approach is far more collaborative. We're a bit nervous for this first major project. Each writer is responsible for a sections of content. We tried to make the assignments that fit each writers' skill sets and interests. As writers we are then responsible for writing all content that fits within those sections of content. We share the glossary.
We share the glossary because we list controls with a link to their definitions. We're using conrefs to manage this (an interim solution is to have tables in the controls reference topics until we can figure out how to replicate our current presentation). This approach has the added benefit of being able to reuse the definitions across products even if the control name varies, which it sometimes does.
This saves on translation costs.
As we develop content to support products, we write more generally, using the strategies of single-sourcing to ensure our content can be reused without change. The concept topics provide the best opportunity for this level of sharing. The reference topics are, generally, specific to the product, but the conrefs allow us to reuse the definitions, at the minimum. The task topics are where the the variations between products present themselves. We have no idea how much content we'll be able to share between products in the instructions. We have set out the following guidelines to help us with sharing:

• Instructions are tagged using the cmd and info elements.
  This means we can apply conditions to either part of the step.


• The point at which a shared topic is broken out into separate versions for each product is up to the writer responsible for the topic.
  This allows us to explore the break point and gain experience.


• Writers tag the topics and the section maps so that when a product map is used to generate a document only the content appropriate for that release appears.

Which brings me to the second part of our new authoring process: building documents for a product release.
We stuck with our earlier strategy of assigning a writer to a release but, in the new model, that writer is responsible for processing the content provided rather than creating and processing the content. They become the point person for a release; they push the document through our process, setting up and managing reviews, publishing the final content as a PDF or CHM, and notifying translation that a document is in the final state.

Labels: authoring, dita, user documentation