Contemplation

Topic Orientation and Reuse

I was in a meeting a few weeks back when the question of content reuse came up. Does topic based documentation really increase our ability to reuse content? What is the return on the up-front investment in user analysis and content planning? I decided to create a simple scenario showing the potential for use.

Consider the following documentation requirement: Your company, Southern Specialty Foods Inc., is trying to introduce “Southern Special Grits” and “Southern Special Quick Grits” (Southern corn based staple in the United States) in the emerging markets. You are required to write a user guide for a box of grits.

Now if you were in India, you'd have no idea what grits were, how to cook them and when to eat them.... Given a box with terse instructions, you would probably just grit your teeth!

So how do we go about documenting this in a way that users can understand and also leave the door open for reuse?

Topic Orientation

Let's try to create a content plan. The user probably wants to understand what grits are. What is the user going to attempt with a box of grits...cook it of course. So, its probably a good idea to show a basic recipe first and move onto more exotic variations later. The topic pool and content layout could be something like this:

Topic Reuse

As you can see, we have reused certain topics ("About Southern Specialty Foods, Inc.", "What are Grits?", "Jazzing Up your Grits") in multiple guides (topic maps).

Multiple Delivery Channels

Consider the task topic that shows how to cook grits. Wouldn't it be nice to create a video that showed how to cook grits?

Voila!

My graphics skills leave a lot to be desired , but hopefully I have made a point. The contents of the task topic "Cooking Southern Special Quick Grits" have been reused to create multimedia content.

Localization

We have addressed the English speaking emerging markets...but what about China, Brazil etc.? The "Southern Special Grits Guide" and the "Southern Special Quick Grits Guide" need to be localized in several languages. Instead of localizing the guides separately, it is now possible to localize topics in the topic pool. Thus the topics common to both guides have to be localized only once! This is huge in terms of reducing localization costs.

We have seen that well designed topics can be reused across products to deliver content via multiple delivery channels in various formats (like product documentation, training, support, HTML, PDF, screencasts). Localization savings can add up noticeably. There are many other avenues of reuse too - across products, platforms, audiences etc. "Write Once, Use Anywhere....", well, ahem..ahem... almost!

One of the unique selling propositions of Darwin Information Typing Architecture (DITA) is content reuse via topic based documentation and minimalism. Of course, such reuse may be possible with other structured formats like DocBook etc. The key is topic orientation.

I hope this article elucidates the potential of topic orientation and reuse. If nothing else, you now know something about grits!

Posted at 06:00AM Jul 01, 2008 by Sowmya Kannan in Sun  |  Comments[1]

The Evolution of Technical Writing

The last few months, I have had the opportunity to work on technical writing assignments using unstructured Framemaker and DITA. My experiences on both kinds of projects have provided profound insights and prompted several questions.

What are the skills a technical writer must have? Obviously, he / she should be able to present information in a cogent and concise manner with the target audience in mind. With today's ephemeral technologies, the writer now needs to think about how to structure content that lends itself to reuse.

REUSE
I use the word “reuse” in the broad sense of the term....how does one take content originally developed for Product A and modify it to discuss Product B, with minimal effort. In my mind, I see this being possible only if the content is somewhat modularly structured, making it possible to pull out relevant areas and reuse elsewhere.

OBJECT ORIENTATION
Perhaps it is my background as a software engineer with an emphasis on Object Oriented Programming. I have a tendency to organize content into small logical chunks and look at content as a tree with branches and leaves. In the 1960s, unstructured programming, emblematic of the “jump” or “goto” statements, led to unwieldy programs, as the complexity of software increased. It was replaced by structured programming which had a more top down approach and modularized functionality, making it easy to maintain. Object Oriented Programming further organized and grouped similar functionality together.

TECHNICAL WRITING – COMING OF AGE
With software being complex and fluid, software development tools, technologies, and paradigms have evolved to keep pace and provide some sanity to the software developer. Has the field of technical writing seen a parallel evolution? Is content being broken up and modularized with an aim to easily rework and reuse? Emerging paradigms like DITA are providing the platform to enable the evolution. Structured formats like DITA, DocBook etc. force the writer to organize information into small, logical, well structured chunks. These well known formats enable the development of content that has a uniform look and feel, and gives the audience a sense of control and direction.

TRANSFORMATION OF THE TECHNICAL WRITER

Software engineers have had to keep abreast of technologies and constantly undergo training in the latest tools and technologies. The Technical Writer for the most part, has not had to deal with the shifting sands of time in terms of the tools used to author content. Adobe Framemaker ruled in the writing community for a long time. HTML provided a way to make the content come alive. With the advent of structured formats and multiple delivery channels, technical writing has become more than just about describing software.
Writers now need to practice “structured thinking” and understand the schema of nested document structures, build tools and processes. The writer's realm has now expanded from just describing software to iterative content model design, development and publication similar to the environment of a software developer.

Does that seem like overkill for technical publications? I don't think so. In my opinion, "the document development life cycle should roughly parallel the software development life cycle".

AAAAH, NEW TECHNOLOGY!
So what does all this mean? Can a writer take to structured, topic-based thinking like a fish to water? Are the tools available to facilitate the transformation? There are new tools that do simplify the task of authoring DITA based content via WYSIWYG editors and so on. But they have their limitations. But are these tools going to stay this way for ever? When I first started developing software in Java in the mid 1990s, even major Java editors were flaky. Later versions of these proprietary tools and other IDEs like Eclipse and NetBeans improved tremendously, with support built in for code completion, refactoring and enhanced debugging support. I am glad developers did not give up on Java early on.

I find parallels to DITA in this aspect. DITA being a nascent standard, has a dearth of good, user friendly, inexpensive tools. However, if as a writing community, we are convinced that DITA is a truly viable standard, it is a matter of time before better tools emerge.

For a writer to be successful in this new world, training in the tools and technologies is imperative. Lack of support leads to hurdles in adoption and expansion. With a comprehensive tool belt and a solid plan, a writer can accomplish almost anything.

Posted Feb 12, 2008

Posted at 02:34PM Feb 12, 2008 by Sowmya Kannan in Sun  |  Comments[1]