Foul Writer’s World

I hate including dialogue boxes in my documentation, especially when they are included as part of a task list. However, writing the task list without including the dialogue information can be confusing for users. I came across the following on a Microsoft website that I really like. I may create some standard dialogue boxes and inlude these in my documentation from now on.

They provide enough information from the user enforming them that they will be referring to a dialogue box, yest the basic design also stops the cluttering of information in the steps.

I received a mysterious email yesterday that simply presented a  nice logo formed around the mysterious entry:

DITA 10-29-08

All well and good but very little else was forth coming.

I was tempted to write something about this but I found something even better over at monkeyPi regarding the very same email.

So here it is a delicious cookie recipe :

White chocolate macadamia nut cookies
2 cups all-purpose flour
3/4 teaspoon baking soda
1/2 teaspoon baking powder
1/2 teaspoon salt
1 cup (2 sticks) unsalted butter, softened
1 cup light brown sugar
1 egg
2 teaspoons vanilla extract
8 ounces (1 1/2 cups) white chocolate baking squares, cut into small chunks, or white baking chips
3/4 cup roughly chopped, unsalted, toasted macadamia nuts

Preheat the oven to 375 degrees F.

Combine the flour, baking soda, baking powder, and salt in a mixing bowl.

Beat the butter in a large mixing bowl until fluffy. Add the brown sugar and mix together until smooth.

Add the egg and vanilla. Blend in the flour mixture in 3 stages and stir in the white chocolate and the nuts.

Scoop out walnut-sized mounds of the cookie dough and place on a cookie sheet, leaving 2-inches between the mounds. Bake for 8 to 10 minutes, until the cookies are golden.

Why still produce manuals and user guides? This is a question I’m beginning to ask myself more and more. People I have spoken to all freely admit to never reading the manual. I myself, rarely read through a manual. So why do I bother? The truth is, I bother because of the 1 person in every 10, ok a 100, which emails back or leaves a comment thanking me for the documentation I produced because it got them out of a sticky situation or improved their own performance. These are the people I still write for, but they are a dying breed.

Granted, I still see the importance for producing written material. Particularly for Knowledge Bases and Troubleshooting. But I find myself increasingly more interested in the technologies behind technical communication rather than the writing itself. I like the idea of new media supplementing the written documents, the use of wikis to give the users a voice, blogs to keep the world informed. Podcasts or Screencasts to guide new users through the features.

I am particularly interested in interactive manuals, because I believe people learn and remember better when they get stuck in. I’m busy developing a new framework for the organization where I work, trying to fit interactive manuals in to a formal structure that will allow for greater reuse. In previous projects where I have attempted to create interactive manuals they have only been partially successful because of time to market.I am hoping with this new framework I can create completely reusable content that will allow me to produce a greater range of interactive manuals, while reducing the time to market for each.

My main tools for doing this are Adobe Captivate and Flash. I also have Mimic 1 but I am not a fan of the MadCap application, although that may change with the release of Mimic 2.

I intend to create “movie clips” that are independent of one another. Which can then, using something similar to DITA’s mapping practices, be used to create a TOC that will link the required movie clips together. What I’m hoping is that to and end user it will seem like one complete movie, full of interactive and learning elements that they will enjoy using and find useful.

At the end of the day I am hoping to come up with something similar to what Microsoft have done with the online training they have produced for Office 2007. To see an example check out the link below:

Microsoft Interactive Guides for Office 2007

I’ll let you know how I progress.

Has anyone got any tips, advice or any other examples?