One of the most common reasons for project failure when converting to a component content management system is writers not making the leap from unstructured to structured authoring. Many writers still resist structured authoring, fearing it will rob them of their creativity and make them replaceable. However, some writers, like Amanda Cross, learned that the opposite is true. Writing with structure makes authoring documents faster and easier, freeing the writer to invest more time in the tasks that they find interesting and that their employers find indispensable.

At the beginning of my experience as a technical communicator, I idealized writing self-contained documents, agnostic of any other documents, perfect for the product and audience. I wanted to enjoy the accomplishment of looking at a finished product committed, forever-unchanging, to the department archive and saying, "I wrote that."

"… those completed masterpieces that I considered permanent fixtures in the museum of technical documentation turned out to be living, breathing documents in constant need of babysitting."

It didn't take long, though, before the unromantic reality of writing software documentation came crashing down around me. Soon, I found that those completed masterpieces that I considered permanent fixtures in the museum of technical documentation turned out to be living, breathing documents in constant need of babysitting. The software was never truly complete; I should have known the documents wouldn't be either. They needed to be updated for every bug fix, new feature, and product release.

Piled on top of keeping up on my existing documents, each new project added more tasks to my queue. Suddenly, the chore of crafting a unique treatment for each topic wasn't the source of career fulfillment that I thought it would be; it was a pain in the neck. It took forever to find where I'd written something when I needed to change it, and I couldn't easily delegate because someone else couldn't predict where they'd find information in my document.

Plus, I couldn't avoid the sinking feeling that the unique treatment I created for each document was pretty much always the same. After all, these documents were for parallel features used by the same audience in the same product for the same use cases. I was clearly wasting time that I wanted to be spending on branching out into different kinds of responsibilities:

• identifying opportunities for new kinds of documentation

• contributing to interface design

• advocating for the user

• being the voice of reason in the seventh straight hour of the design meeting

"… the very part of my job that used to seem like the ultimate goal, now seemed like it was getting in the way of the real goal, serving the customer."

Only a few years into my career, I realized I'd done an about-face on my original attitude. Crafting individual structures, the very part of my job that used to seem like the ultimate goal, now seemed like it was getting in the way of the real goal, serving the customer.

I'd Never Really Wanted to Reinvent the Wheel

In college, you work on standalone projects for a couple weeks at a time. In business, projects can spawn other projects and stretch out in perpetuity. My mistake early on was thinking that the satisfaction I got from completing one project in college had to translate to completing one project in the business world. But, in fact, I could get satisfaction from completing documents that really helped people, even if the audience analysis, document structure, and page design had been done as part of other projects.

So to free up my time to accomplish more, I began reading through the documentation that already existed to find the structure that was already there. (By the way, if you've ever read through an existing document to get ideas on how to write your own document, you've already begun down this path, even if you didn't know that the "structure analysis" buzzword applied to what you were doing.)

Over the years writers had misinterpreted (or disregarded) the existing structure, so I also looked for the kinds of information that were misplaced. For example, if a previous writer had put information about corporate policy in the definition of a database column, I still wanted to have a place for that corporate policy in my new structure. I didn't want to leave anything out just because someone had typed it in the wrong place.

Trying Out the Structure

Soon I had designed a structure with a place for everything, and I was ready to try it out. Not only was I able to produce 600 pages of documentation for the new project single-handedly in about three months, but at the same time I was able to use my time to participate on the design team. I had time to comment on every iteration of the design, argue issues of usability, and make myself the final authority on naming--things to which I'd never been able to give the time they deserved.

"Freed from deciding which details to put where on a case-by-case basis, I had time to focus my attention on getting a deeper understanding of the content that I could then communicate to my readers."

And the documentation was really good. Freed from deciding which details to put where on a case-by-case basis, I had time to focus my attention on getting a deeper understanding of the content that I could then communicate to my readers. The documentation was done before the product, with continuing product development actually depending on the documentation.

The Real Test

It was an achievement, to be sure, but so far I'd been the only one using the structure I'd created. It didn't feel like its mettle would really be tested until someone else tried it out, ideally on an existing module to demonstrate that there really was a place for every piece of information. We got that chance when new writer Amy was assigned to update an existing module, and a rough one at that. I was an advanced user of the product, and after reading the documentation, I didn't understand a thing. The documentation made the product seem much more complicated and difficult to use than it really was.

Even so, when I sat down with Amy to review the structure, talk about the kinds of information we'd expect to see in each section, and discuss the reuse opportunities, she looked skeptical. Previously, these modules repeated information in as many contexts as the writer deemed necessary, but the new structure called for a place for everything and everything in its place. You can always link to further information as needed.

The idea of having exactly one predictable place to put each piece of information was new and a departure from what had always been done before. Still, Amy is open-minded and enthusiastic about improving the documentation, so with an offer to help any way I could, I left her to give it a try.

The Moment of Truth

This is where the story gets short, because I had almost nothing to do with the rest of it. Re-writes can take as much as six weeks, so I waited till the next week to peek over the wall to ask our fresh face how the re-write was going. Great, she said, it was almost done. I was surprised that it was going so fast, but she told me that the structure made it easy. With a place to put everything, she said, it just fell together.

The last time I touched the document was to review it. Indeed, with a place for everything, the document had fallen together in a way that made the product easy to understand. The writer's attention was available to focus on the quality of the content, without having to puzzle out where to put it and the SME reviews were quick and easy.

"Far from preventing the writers from being creative or making them dispensable, the structure freed the writers' time to be more creative in the arenas that made them really valuable to the company."

Success! Far from preventing the writers from being creative or making them dispensable, the structure freed the writers' time to be more creative in the arenas that made them really valuable to the company. With document rewrites falling together, they could become product experts, communications experts, and creative problem solvers that the rest of the company came to for advice. Structure had even left me enough time to smile over this accomplishment.

DCLNews Editorial
June 2008

Send this Page to a Friend

Printer-Friendly Format