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 0 Comments   

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

Normally, it takes something akin to an earthquake to get me out of the house and into the big smoke south of me. Add to that sad state the fact that November is novel writing month and, worse yet, I'm behind on my homework, getting me to do anything is nigh on impossible.
Today, Saturday, I roused myself just like it was a work day and I dragged my pathetic self down through the winding traffic lights and construction detours to sit in uncomfortable chairs and judge other people's work.
I know that the STC has its fair share of cheerleaders and detractors. I don't care. The STC has offered me some benefits and one, last year, was the input from judges at the annual competition. I was sad that my shining contribution won no awards but it was interesting to hear back from someone (other than my in-house reviewers) who had actually looked at the manual. Feedback from other writers is great, they highlight your achievements and point to places where some improvements could be made. The feedback I received, even without that award, provided a different view on my output. It's hard to judge your own book when you know all the reasons for its imperfections.
It's never my fault, you know.
So, I decided that in spite of all the notches against volunteering to judge at this year's competition, I'd do it. It has benefits for me: I meet other writers, I get to see some writing samples that I'd miss otherwise, I get to give to my community, and I get a cool thank you present. I also got a better view of how it is to see something from the other side (without the pressure of trying to get the bloody product to work the way I think it should) and maybe get some insight into my own work. It's important to have clear motivation when you act, when you know why you're doing it you can do it better (or at least feel like it has value).
I'm looking forward to seeing how DITA changes our product (product to me is my manual) and I'm hoping that it takes my manuals from lacking merit all the way past excellence into distinguished.
I know it won't happen this year, or next, but by the time we've got it down (say, five years from now?) I expect that my submission will blow you all away (even if you have no idea what strain rate really means for a heart).

Labels: competition, judge, manuals, STC

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

Here's why I wouldn't do our DITA project without a CMS (even though we're doing the DITA project without a CMS): In one section of one manual, I have 133 topics. That's my smaller section. I don't have the numbers at hand for the larger section but I am responsible for approximately 400 topics. Keeping track of that many fluttery bits would drive a sane person mad.
We think we're being very clever, though. While we wait for the CMS and authoring tool to talk to each other, we use both sides of our brain. Our left side is busy organizing methods to limp through production without the CMS. Our right side is busy imagining what we need to make the final process, post-integration of CMS and authoring, happen with as much safe, clean processing as we currently have (unless you're one of the writers who shall remain nameless but who cannot make things work, it's like there is a curse on that writer).
Right now, we've been developing sections, zipping those up into a single file, and putting that file into the CMS. This has led to some interesting results as we all have different versions of the tools we're using to zipitdodah. Workaround number 722 is discovered and is carefully documented in our playbook.
We're looking at modifying this somewhat. Right now we all work off our our folders on a shared drive or our computer. Sometimes we like to work off site and not all of us have danced with IS to get access to the servers at work from off site. Hmm. But, what we're thinking of doing is collecting our work folders together. When you want to go off site, take copies of some files with you. Load them back up when you return. Here's the thing that took some time to wrap some heads around... it doesn't break my work to point to your file that is out of date. As long as the file name (and ID) remain the same, my link works. When you bring back the cool new version of the topic, drop the file into the same location, and my map will pull up the new version without a flicker of concern.
Fortunately, our mix of skills means that there is always someone available to work through a problem.