Foul Writer’s World

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.

The organisation I work for are creating a new web based platform. This platform, a question creation and assessment delivery solution, is designed to be rolled out in multiple languages. The architecture of the application dictates that the translation is done on-the-fly. Translation language is predefined as a user preference. This is easy enough for the application as terms displayed are basic terms (Save, Cancel, Create, etc.,) and the UI is designed be simple and easy to follow. With the help, it just isn’t feasible to do any sort of translation on-the-fly. Automatic translation just isn’t advanced enough yet.

After spending a few days discussing with developers alternative solutions for the help we came up with a method based around the DITA framework. Help would be created in a per topic method, each topic would contain details about a specific task. The tasks would be documented in a manner that allowed them to be read independently or mapped with other topics to create a full and thorough help file when needed. All this help could then be translated.

The help, plus translations will then be stored in a database and the correct language of help displayed depending on the user profile. We have decided on a very basic display for the help, something simple like Google did with Analytics so as not to distract from the information. I’m looking forward to seeing how the outcome will work.

It has been my first proper sortie into the world of DITA. I have decided that I while I like the principles behind DITA, the current toolset leaves a lot to be desired. I’m glad that a majority of the documentation will be done in plain XML for easy translation and importing in to the database.

I’ll keep you posted on how it goes.