Others Share My Dream

On Techwr-L today, Craig Cardimon asked, "Which of the following makes the most sense:

1. Describe all the icons in one topic
2. Describe the icons screen by screen, including repetitious descriptions for the more frequently occurring icons
3. Describe the frequently occurring icons in one topic, and the screen-specific icons with their respective screens"

It gave me the opportunity to write the following:

---

Make each icon description a snippet in your tool / format you are working with. By doing so, in the future, any place *the user* needs to read information about the icon, you can include a reference to the appropriate snippet. Further, in the future, when you need to make a change to the icon description, change the snippet, do "something" (macro, click a button in the tool, whatever) that will update all the references to the snippet.

Write each description only once.
That's the dream I'm working towards fulfilling each day.

---

I am always learning, even after being employed as a technical writer since 2/10/95. If you pay attention to this blog, you know that I wrote the documentation for a software company in Cedar Rapids for a dozen years. Thinking about what I wrote and how I wrote makes me chuckle a bit because, frankly, I didn't use the concept above nearly as much as I should have in my daily work.

Here's a brief example. There were a trillion (or so it seemed) screens in the system with a check box called "Change Print Options" and no matter what screen you were on, if you selected the check box and clicked an "action" button (like "Submit" or "Next"), a window appeared on your screen and you could make changes to the way in which a report, list, or "something" would be printed. The options included whether to duplex and the name of the printer. In my field-by-field information, I had text like this:
|
Select the Change Print Options check box to change print options. Refer to Change Print Options for more information.
|
Even after over a dozen years of working there, I never got to see the dream I described above to Craig come true. I don't think I even knew I had the dream or could articulate it, if asked back then, but looking back, I think I must have known, subconsciously the dream existed. I say that because I eventually settled on a single version of the Change Print Options topic. I remember that I had two deliverables:

• in the online Help, I inserted a hyperlink to a separate HTML page where this information was included. I started doing this relatively early in the days of creating and maintaining WinHelp files - that blessed old technology that I loved working with on a daily basis.

• in the PDFs, if there was a change to the text, I *manually* went into each Word doc and replaced the text. That's over 200 PDFs. That's a lot of work! 

What I should have done was include a reference to a single Word doc with the Change Print Options verbiage so that I didn't have to update 200 Word files. It could have been so awesome to have that set up and to do less work than I had to do to do my job. It was impossible to do, at the time, but if I could have articulated the dream and then made it come true, it would have radically changed the way I did my work and the way in which the documentation was designed.

Where I work now, we are in the midst of a big push to be consistent as we work to eliminate the inconsistencies that have crept into our documentation. For a single "system" each client gets their own user guide. There is no single source, right now, so we might have in one manual (borrowing from another thread):

We are in the midst of a big push to be consistent as we work to eliminate the inconsistencies that have crept into our documentation. For a single "system" each client gets their own user guide. There is no single source, right now, so we might have in one manual (borrowing from another thread):

---

To access List Trends, click the History button in the Main Screen.

---

And in another, for a different client:

---

To access List Trends, click the History button in the Main Screen. Click Close after you have reviewed the information.

---

And for yet another client:

---

Viewing List Trends
You can view list trends that have been previously entered in the system.

1. Go to Main Screen > History.
2. Edit the data. You cannot edit the information unless your user ID has been assigned the "Omniscient" user role.
3. Click Close.

---

My current project is to consolidate the multiple ways we have previously told the user to complete a task into a single way and then, someday, use that text in all user guides as part of a single source solution. Right now, we have separate Word docs and no single sourcing. If something changes that affects all clients, we write it once, copy / paste into each applicable user guide.