When you design a structure with a place for everything, the document writes itself
By Amanda Cross, special to TheContentWrangler.com
My first job out of college was documenting reports that were spit out of a mainframe. I received a copy of the report, opened the Microsoft Word template, filled in the blanks, and wondered what I was going to do with the rest of my morning, let alone the rest of my life. I couldn’t believe I’d gotten a college degree for this. This job could be done by monkeys. Or even programmers.
Having to fill in this stupid form was relegating me to a mundane task. I never got to learn anything about the subject matter or practice the craft of writing. If only I could give my topic the unique and special treatment that it deserved, then I could find satisfaction in my career.
Fast-forward a few jobs later to an environment where I could give the unique and special treatment to my subject matter that I’d always wanted. It was fun and interesting to become an expert on a topic and craft a fine document. It was like projects in college: I wrote a self-contained document, agnostic of any other documents, and enjoyed a sense of accomplishment looking at the finished product committed to the department archive, done and forever unchanging.
Documents © Galerie André – FOTOLIA
Soon, though, I wasn’t satisfied with working on one little document at a time. I wanted to be involved in lots of different kinds of projects. Even more, I wanted to branch 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
But there just wasn’t time. 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. Each new project also needed as much attention as an infant, even though it was soon apparent that the outlines I wrote for new topics turned out to be pretty much the same. The more similar the better, I learned as I finished more documents, because the little differences in structure just make it more difficult to find the impact when changes invariably occur.
Having to come up with this stupid unique and special treatment for each topic was relegating me to a mundane task. I didn’t have time to expand my skills. If only I could focus on the quality of the document instead and just collect it in a predictable and time-saving form, then I could find satisfaction in my career.
And that’s how I came full circle on my opinion about structured writing. The very part of my job that used to make me feel like the walls were closing in was now the solution I sought to free me from the limitations on my time.
I’d Never Really Wanted to Reinvent the Wheel
My mistake at that first job out of college was blaming the Microsoft Word form when it was the subject matter itself that was fantastically boring. No amount of time spent wordsmithing was going to make those mainframe reports a pleasure to document, and having to re-invent the structure of each document would have just made an already dry process take longer. As the fresh face out of college, I wasn’t going to get a better assignment any time soon, so looking back on it, I was lucky to be on the bottom of the totem pole when the downsizing came.
But this time, downsizing wasn’t going to change things for me. I had to do it myself. I began by 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.
When adopting a new structure based on the old documents, I didn’t want to leave anything out just because someone had typed it in the wrong place. 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, just not the same place the previous author had put it.
I gave everyone in my department, as well as internal customers from the sales, marketing, customer service, and customer implementation departments, an opportunity to comment on the structure. A few minor adjustments later, the structure was ready to be vetted.
Trying Out the Structure
I was beginning the documentation for a newly developed project, and the structure was everything I’d wanted it to be. 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.
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. Amy’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.
Success! Structure had even left me enough time to smile over this accomplishment.
Next is to auto-generate all of the content that doesn’t need the writer’s skill set–things like technical specifications and entity relationship diagrams. Some of this stuff, after all, could even be written by programmers.
About the author
Amanda Cross is a Technical Writer and structured writing evangelist in Indianapolis, IN. She’s a senior member of the Society for Technical Communication and currently on the ballot to become the Vice President of the Indiana chapter. She occasionally records her thoughts on content management, poorly mannered SMEs, and how documentation can save the world at Content Management Musings.