Manual writer

We have product

2008-07-06T12:03:00.000-07:00

Indeed. We have produced several documents using DITA. The issues with our CMS and editing tool continue to give us difficulties but we can see a horizon now.
Lesson: It's almost impossible to change your tool set without running into lots of problems. That's why there are consultants out there. They hold your hand and walk you through the thickets and get you to the other side. This is the consultants as scouts model.
We needed to shift because our workload is increasing. Unfortunately, we were not able to make the shift before our workload increased. We have learned some things and are being able to fix some problems ourselves. We're hanging in until some additional help is available. Instead of scouts, we're hiring helicopters to lift us out of the danger zone.

Dreaming

2008-05-03T12:57:00.000-07:00

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:

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.

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.

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.

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.

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.

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.

Somewhen a robot is doing my job

2008-03-01T14:13:00.000-08:00

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.

Copy-to Attributes

2008-01-24T08:58:00.000-08:00

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.

Demented

2008-01-06T11:57:00.000-08:00

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.

Filtering Content

2007-12-08T15:18:00.000-08:00

There has been a discussion on one of the lists about filtering content in output from DITA. There are many shades of grey, or gray. We have settled on using the topicref as the basis for the filtering.
We have organized our content into sections, which works very well for our stuff, and each writer is responsible for various sections (in their role as content author). We collect these topics into maps that will be referenced by the map created for a particular instance of a product manual.
Because the section maps filter the content (I can't imagine trying to pull together the thousand odd topics required to build a basic manual), the content author uses them to determine which products carry which features (which can change over time). The topicref, therefore, always points to a topic that exists. The topics are not filtered out by the attributes of the topic.
Within each topic, we may have sections that do not apply to a product, so those are filtered by their product attribute.
The topics, some people have argued, should be as self-describing as possible. Now, for us, the features trickle through our product line. It is rare that a feature is truly product-specific for any length of time. Also, we store our content in a content management system and the topics have metadata that is applied there. So, we can use that metadata to more fully describe the topic.
For the information architect, a role we all play at one time or another, the sections they pull into the final manual are like black boxes. We content authors ensure the information is filtered correctly, structured correctly, and is complete for the product at hand.
When our product teams whisper, the day before the deadline, that a certain feature is pulled, well, we change one attribute in one location to get the result we need.

I can see the light

2007-11-30T07:07:00.000-08:00

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:

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

I created a wee monster that looks like this:

Do the first thing.
Repeat these things until you have everything you need:

Now do this.
Do this.
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.

Quality in Manuals

2007-11-11T09:09:00.000-08:00

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.

Why did I Volunteer to Judge?

2007-11-10T16:25:00.000-08:00

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).

Converting Legacy Content

2007-11-05T17:12:00.001-08:00

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.

Transition in Authoring

2007-11-04T15:47:00.000-08:00

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.

Keeping track

2007-11-01T06:46:00.000-07:00

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.

Mercury in Retrograde

2007-10-26T20:34:00.000-07:00

There is an astrological concept of planets going retrograde, apparently travelling backwards through the signs, then going direct and travelling the usual direction. Mercury does this a few times a year. It's doing it right now.
What does that have to do with DITA? Nothing, directly.
But, I'm realizing that I'm falling into one of those dreams where robots and men fix bolts and weld seams as I roll along the assembly line. Pray that nothing goes wrong. I hope I'm being made by alert, happy workers.
I am actually enjoying the transition from a Jane-of-all-features to the mistress of some.
I've been working on an analysis package for a couple of years now. It's a strange duck in our product line. There is only one other project that inspires more fear and dread: the transducer care website.
So, when we decided to parcel out content by subject area, rather than product, I took analysis. I'm slogging through specifications and I'm really feeling like I'm making a contribution. Except, I just found out that we've not been configuring our simulation correctly and I've been saying product x has feature y when it doesn't. It seems to, to me, because I'm not applying the right filters to the setup. All my simulations are, essentially, of the same product, even if I think I'm setting up different products.
We've now documented the setup procedure (and shared it with some other folks who need it and didn't have it) and I'm reviewing my work. I thought I was about half-way done and now I'm walking back to the starting line, like Mercury in retrograde, going backwards through my work, and then I'll turn around and go forward again.
To give myself a break from this sad fact, I decided to put some extra effort into my Six Sigma project. I asked around and got a procedure document that described the current process (that I am supposed to improve) and I spent the day working on process flow and dependencies. Late in the afternoon, I took my work to a SME for a quick review and on the first page he said, oh, you were working off the old process. We have a new process, you should use that.
I left work for the day shortly after that.
Next week, I will complete my retrograde and go direct.

Come back to the story

2007-09-22T17:43:00.000-07:00

My wife says I'm an introverted extrovert. She also says that I'm fine talking with people as long as they can't interrupt me. So, that makes me a good performer.
Normally, I just go along with these notions of hers but today I'm having to really think about it.
Yesterday, I had an opportunity to reach out to some folks who could really contribute some great stuff to my job. I had stage fright. I could barely speak and my voice came out trembling and weak. I repeated my inane three sentences over and over. I just about fainted.
And they just sat there staring at me.
Here I was asking them to help me do my job and they were already feeling that the company hung them out over a croc pit. I should have used that, I should have told them that cooperation between them and us could make a better world. Suddenly, I have the sound of children's voices trilling out the tune "It's a Small World" and I can hear the hysterical laughter starting in the back of my head.
Hopefully, the people who train our users will feel that their feedback to the team that writes the manuals will be worth their time and effort.

Don't ask me, ask the customer

2007-09-19T16:48:00.000-07:00

Like a number of technical writing teams we have users and we have customers. They are not the same people, they don't have the same goals, and they don't have the same level of access.
Our customers are the project teams. The managers responsible for getting the product out the door. They have customers and users, and again they aren't the same people. Ultimately, our customers, the people who pay for our services and place the value on our services are the shareholders. They don't come down to the cubicle I sit in and tell me that I can or cannot do something, they have a much more effective tool set.
The shareholders tell the executives that they want to make more money. The executives figure out whether they can do that by producing more market share, reducing development costs, or by firing a bucketload of employees (and dumping their workload on the remaining employees). It seems to come down to a mix of options. Get more product releases out, sell more of them, and reduce the cost of producing them.
Lovely. Well, all things considered, producing content that accurately reflects the product and provides meaningful assistance to the folks who end up using the products is a snakey line dance. With more product releases we have to march through our process more often, making small and large changes, and regurgitating content on an assembly line model. Can do. Wait, though, our users are different (not really within a single product line but across product lines) and we want to increase sharing so that we can pick up the pace on production.
We have been tracking down the people who meet users, for real, and asking them what the users need. The results are diametrically opposed to the trend to reduce content and promote reuse. Dang.

Working Title

2007-09-15T14:19:00.001-07:00

I'm trying to get permission to write more freely about our DITA activities. It's very different in a corporation.
For most of my career, I've worked in relatively small shops where there is a reliance on outside sources for experience and information on technologies and techniques. I was always encouraged to absorb and share information and experience. In a corporation, they just hire you; if you need new input, they hire that. But, what you develop out of that combination of experience and instruction becomes both confidential and a competitive advantage. Or so I'm told. I'm curious, how can I know that my processes are a competitive advantage without knowing what my competitors' processes are?
I may never know the answer to that question.
But, I am learning how to operate within a corporation. I've started thinking of it as a fictional environment. A place where the suspension of disbelief is integral to success. To fully experience the fantasy, you must be able to leave reality at the door.
I have learnt some excellent lessons so far:

When in doubt, defer the problem up the chain to the person responsible for you.

Learn how to ask, appropriately. Form your arguments ahead of time, put them in writing, and be skillful in your distribution. Do not antagonize those you need on your side by leap-frogging them in the process. Give them a chance to say nothing, or no.

Get down with numbers. Even if the person you're reporting to is not a numbers freak, the hands on the reins are.

Regardless of the product, the ultimate customer is the shareholder/owner.

This is your job, not your life.

Some of that may seem cynical to you. I don't think it is. I come home after a hard day of slogging and I sit down to write. I read about writing. I love writing. But, in the amusement park of employment, there are restrictions and fictions that I need to respect if I'm going to succeed in my personal goals. I want to be happy. Trying to change how a corporation operates, from a cubicle in nowhere, isn't going to make me happy. Now, if I could write like some of my favourite authors, I could enjoy a bit of poking fun at corporations and the mad, mad world that they give rise to.
I am grateful that I'm working in a corporation and have learned to walk the walk well enough to be a kept woman. I get to play with stuff that fascinates me and I get to work with some incredible people. It's almost like being in love.
When the network gets wonky, when the engagement surveys come out, when I sit through hours of drivel from the talking heads, and when the path to my objective is strewn with cultural icons and practices that seem almost normal but leave me feeling disorientated and alienated, well, I look at the whole picture. These are the folks that have the money to pay for me to play in my sandbox. I'm not ten people. When I was younger, and had more energy, being ten people in a small company was a blast. Now I'm like the cartoon wolf clocking in and clocking out.

Over the hill

2007-08-18T17:23:00.000-07:00

We're cresting the hill. I was reading some guidelines written up by other members of the team and I realized that my understanding of what we're doing and their understanding was different enough to make me nervous. It's bizarre. We meet nearly every week and discuss what we're doing and we think we agree (language can be so imprecise!) and off we go. It's not until we got the bright idea of writing down what we know that I got to really see into the process from another viewpoint entirely.
Some of the misunderstanding comes down to basics like what is a topic and what is the role of a map in constructing a sequence of content.

What is a topic?

Many of our legacy files contain topics that contain instructions on how to achieve a particular goal. These topics are consistent with a single Help topic. They are simply structured.
There is the title, starting with a gerund (Running the Race), sometimes followed by a paragraph, or two, of information, perhaps a note, warning, or caution, then the procedure title (To run the race), and finally the steps. Each step consists of an instruction and some include some additional information. More often, now, we write our instructions so that the additional information actually becomes part of the next instruction. For example, the instruction: Select the impulse engine speed. The Directional/Destination Option dialog box opens.
Becomes: Select the impulse engine speed.
And the next step begins: In the Directional/Destination Option dialog box, enter a direction or destination.
So, we have some basic information. When I convert legacy content, I leave this topic intact except for the procedure title, which I delete. Many of the legacy topics that were converted to DITA by coworkers are much more fragmented and I spend long hours, or so it seems, stitching them back together.
The key issue seems to be this: at what point does the introductory text become a separate topic?
How much preamble, discussion, or background is appropriate for a task topic? Where is the limit?
When I was reading the guidelines collected by coworkers, from what source I'm not sure, I realized that we were about to carve this breakdown into our processes; I am ashamed to admit that I panicked. I actually began to rewrite the entire document and truly, I don't have time for that. So, Monday means a new round of discussions with my compatriots to hammer out what a topic is and how we perform the conversion of legacy content.
I'm ready this time. I have examples!

What goes into a map?

I'm hoping that by deciding what constitutes a topic will also clear up the strange idea that somehow we're going to stitch these orphan topics back together in a map. I'm going to walk through the entire process on Monday (or Tuesday, depends on when I can get a room with a projector).
We're writing as SMEs now. Where we used to be individually responsible for a product, we're now responsible, as content developers, for content areas. I'm modes and math. That means I create a sub-map of everything our customers need to know about modes. Then as information architects, we're responsible for specific products. So, we'll drop these sub-maps of topic areas into our product maps (according to our specifications governing what goes into help and what goes into print). Lovely. So, we each have two roles: content developer and information architect. I'm not really sure that information architect is the right nom-de-plume for the role. It's really a rote responsibility in some ways. We have specifications that dictate what goes into what document and what documents we provide. Easy. In this role, we're more the shepherd, moving a document through the process of review and release. We don't really deal with the information or the architecture.
It really is a bold new move on our part, far more adventurous than we really are.

Meeting in the corporate cyber-space

2007-08-12T13:54:00.000-07:00

I wrote this one day these week.
I spent several hours in meetings. That's not too unusual in this day and age for a corporate citizen (I figure since I'm a citizen of one country and resident in another, I might as well be a corporate citizen... shades of Jennifer Government). Today's meetings drove me nuts. The first one was scrambled by technical difficulties. The second one is detail-intensive but went along well because we've got the process down flat. The third meeting bored me until I went back to work and just let the speaker speak to
me.
The first meeting's technical difficulties are endemic. (I often have trouble differentiating between endemic and systemic, but I think I've got it down now.) We are a large corporation, we have people in a number of locations, and yet, unless it is a company-wide meeting (meaning we'll all supposed to attend), the technology is not really supporting our requirements.
If your meeting is a low-priority, you can use the conference call option; this is the most reliable method. It is also pretty flexible because every meeting room has a phone and if you can't get one of the meeting rooms, participants can sit in their cubicles.
The next level up involve a video conference. There are a few, well-used meeting rooms that can be used for video conferences. The video conference seems to be easier for participation, there is something about the visual that improves participation and understanding. We have a very limited number of video-conference rooms and they are heavily used. The technology, for the most part, works though we do have some transmission issues and the images transmitted are a tad fuzzy and disjointed because the transmission cuts in and out.
Finally, if you have a fairly large meeting with more formal presentations, we have a couple of rooms that can be used. The tools are apparently undocumented and each time I've participated in one of these, the first ten to fifteen minutes are spent finding someone who knows how to set everything up so that the presentation can be viewed in all locations. Today, we spent time trying to connect the two remote sites. It wasn't that the people didn't know how to set up the conference, but the technology just wasn't being able to carry the load. We could connect both remote groups with limited capacity or one remote group with full capacity.
After fifteen minutes, I left to join another meeting - a phone conference. I sat at my cubicle and answered questions, listened for information, and arranged my day's work.
Right after that, I dialed into a webinar, the new distributed seminar/presentation mode. There are several tools for these webinar presentations. Some perform better than others. I prefer the automated dial-in to the operator-assisted option. More than once I've seen the presentation start on my computer screen while I'm left listening to canned music.

Dancing on the head of a pin

2007-08-04T19:20:00.000-07:00

Yesterday, someone asked me how I had time to do all the things I do. I don't. I don't have the time to do all the things I think of doing, plan to do, expect to do, or want to do.
More and more, I'm finding that I perform a triage on my ideas. And to make getting there easier, I've set aside time slots in my week to make things happen the way I want them to happen.
I've been involved in two huge projects at work, aside from keeping up with my work, and I have finally realized that I need a schedule. Not a schedule in the sense of milestones and deadlines, but a schedule in the sense of Monday afternoons I study cardiology and Friday afternoons I work on my Six Sigma projects. In between, I have a half day on Wednesday that is devoted to research (either Six Sigma or technical writing). So, that means I have to be more productive during the other 3.5 days.
So far, I've found that setting aside specific times for research and specific project tasks, I am not disrupted during the rest of the week.
That said, here's what I've learned this week:
Not everyone can write to a specification. This great epiphany arose out of a discussion with some folks about DITA. During the conversation, I was asked several times questions that sounded remarkably like: what if I want to stand on my head in the corner. I found myself asking in return, why on earth would you want to do that? What if my audience wants it? Pretty strange audience; you're essentially saying that years of research done by people who sit around thinking about this stuff, who get paid a great deal of money to understand the theory and practice of communication, that research is useless because on some whim of some marketing department you're going to deliver your content in iambic pentameter (which, by the way, you can do while conforming the DITA architecture).
People who can't understand the product, the audience, and the purpose of the product are found bounding about in the field of dreams chasing the perfect user manual. And that means that they can't be constrained by a structure that provides a consistent organization of information. And, you can write content in the DITA structure that does not conform to the rules of the context tags; I can write whatever nonsense I want inside the <cmd> </cmd> tags.
I find it a relief to open up a fresh page and have sign-posts appear that say, for a task, you want to follow this order of things. And, seriously, if I really wanted to mess with the structure, I could. But, I like to share and to share, I need to consider others.
DITA gives us a nice structure to push content into. The writers that come and go at my job tend to be the ones that want to tweak the presentation of the content as they're writing. The rest of us rely on the templates and the process to handle the layout for us, we focus on what we're saying and that's good enough for us. In fact, it means we go home at the end of the day having produced content that routes through our DTP process without hairballs.
Having content that gets through a routine publication process without challenges means that I spend more time understanding my work and doing real work. The work I like to get paid for.
Also, moving to DITA has meant that we writers get to content experts. Instead of knowing a little bit about all the features in one product (which, by the way, in my case tend to be features that show up in other products... maybe with a different UI, but the same feature) I now get to delve into understanding a set of features and I document those for all our products. I find it satisfying to get to a level of understanding that could provide better content for the end users (mythical as they sometimes seem).
As happy as I am to be using DITA in this time and place, I am not a flag-waving DITAite. In our case, DITA is a great solution to a problem. It expands our sharing and is projected to improve our level of production to keep pace with the drive of the company's goals. Our products share enough common content to make our concept topics transportable. Our reference content may be tailored to each system, but it's derived from a core set of feature names and functionality. Our tasks vary the most, with the different UIs on each product presenting the biggest hurdle to simple single-sourcing of step-by-step descriptions of processes.