Side Track

I just generated a PDF of a draft of a user guide I am working on. I've included the obligatory front matter and Chapter 1 starts on the 23rd page.

And we ask why users don't read our stuff.

:-(

Types of Reuse

Scenarios of reuse

There are four scenarios within which reuse can occur:

• Same content published in different media
• Same topic in different documents
• Same content within many topics
• Slightly different content within one topic

The first is very elementary, for example, outputting the same document as a chm, web help, and as a PDF. This is the equivalent of changing the paper in the copier from canary to goldenrod while running the office Christmas party flier and saying you are reusing content. Not very interesting and I'm not going to talk about it.

Same topic in different documents

The next scenario, using the same topic in different documents, is perhaps the most common and most efficient way to reuse content. There are a few requirements to reuse content in this way:

You must write modular, stand-alone topics. DITA and Information Mapping are both good models for writing modular topics. The usual restrictions apply:

• No transitions from or to other topics, such as, "As we said earlier..." or "In the next section..."
• No restrictive references that limit reuse
• No embedded links that create dependencies with other topics

The first two requirements fall on the shoulders of the writer. Avoiding transitional phrases is easy enough; it's the need to avoid restrictive references that requires foresight and new sensitivities. For example, many writers would write, "Click Configure > Firewall > Access in the navigation pane on the left," without a second thought. On second thought, however, that navigation pane might end up on the right if the UI is localized for Arabic. You can't just hope the translator would know that. Other restrictions might include mentioning specific products in a topic that might be applicable beyond the product you're writing for. For example, the conceptual topic "How Access Rules Work in the Sentry 2X" might also apply to other product models as well, so the title "How Access Rules Work" would be less restrictive. If the reader is in a document called "Sentry 2X Configuration Guide" she won't wonder if the topic applies to her.

The third restriction, including links that create dependencies, is similar to the second, avoiding restrictive references. I separate them because your composition tool can help in the case of links. In DITA, for example, the link between Topic A and Topic B is not coded into Topic A or B. That relationship is defined in a ditamap, a third file that exists independently of the the two topics. This enables a writer to take Topic A and not have to take its link to Topic B (meaning the writer is free to take A and not B). If you are serious about reuse, you need to have a composition tool that lets you define links independently of the topic content.

Use ubiquitous graphic formats. The best format for graphics is .jpg if you wish to maximize their reuse across multiple media.

Be able to save the topic as a standalone file. Essentially, this establishes the portability of the topic. And while we are on the subject of files, get used to naming your files in all lowercase and without spaces. All operating systems can deal with that convention, whereas some cannot handle mixed case or spaces.

Pull discrete files into a document by pointing to them. Your system needs to build documents using structure files, that is, files that define what content to include, but do not contain the content itself. In DITA, this is done with a file called the ditamap. It points to topics and other ditamaps, defines sequences of topics, any parent/child relationships, and can contain relationship tables to define how topics link to each other within the context of a particular document. Metaphorically speaking, it is the blueprint that makes a particular set of content legos a Ferris wheel and another set (including many of the same legos) a firetruck.

Next blog we will discuss using the same snippet of content across multiple topics.

Reuse: A side trip

Before continuing with the technical details, a brief look at reuse from both sides.

First listen to this: http://www.youtube.com/watch?v=bcrEqIpi6sg (Joni Mitchell singing "Both Sides Now" in 1970)

And then to this: http://www.youtube.com/watch?v=tKQSlH-LLTQ (Joni Mitchell singing "Both Sides Now" 30 years later

It's one thing to write the words; another thing entirely to have lived them. Enjoy.

Architecting for Reuse

In the year 2000...

OK, Late Night fans imagine me--Conan O'Brien like--dressed in black with a flashlight under my chin chanting the above heading (which Conan continues to use even though we are long past 2000--it just has a nice ring to it).

By the year 2043 I predict that we will have written every sentence that we need in order to document anything that can get invented. At that point, it will be unnecessary to write any new sentences, and our job will be to assemble those we already have to meet the new needs. We will be in the age I now dub "Semantic Green" because the emphasis will be on applying resources to the reuse of what we already have versus creating wasteful, redundant prose. (By the way, music achieved this status in 1978; there has been no new music after that year.)

Some of you may say, "Mike, you're kidding," to which I reply, "Well, duh, of course I'm kidding."

Seriously, folks...

After hearing the reuse and content management talk now for years, I have suddenly found myself immersed in actually doing it. (Oh, I've dabbled with conditional text over the years, but that was the extent of it, and I was never in a situation where it seemed to be that important.) Although my prediction above was tongue in cheek, it describes a reality that is upon us today, namely, the purposeful reuse of content (versus the opportunistic reuse of content). The latter is epitomized by the phrase "Why reinvent the wheel" and the former by the phrase "Let's invent one wheel that will fit not only cars we build today but cars we might build tomorrow (or might be building in another plant right now that we don't know about)." OK, the latter phrase got a little wordy.

So I'd like to start a series of blogs for awhile that explore not only what it means to write for reuse, but also what it means to plan for reuse. And specifically I would like to examine what the role of an information architect is when it comes to reuse.

A few disclaimers up front.

• I have drunk the DITA Kool-aid to the point that I am as blue as Pappa Smurf. A lot of what I will talk about comes from my DITA perspective, but I think it applies to any composition environment that tags content. And some of what I'll talk about doesn't even need that. I might talk about DITA a lot because that is what I use, but I will leave it up to the reader to translate the principles I examine into your environment.
• Although reuse scales well within a content management system, it can still be planned for and used within rudimentary content management environments. If you can create folders, you've got a CMS. Anything above that capability is icing on the cake.

Benefits: The short list

I will talk more about benefits of reuse as we get into specific examples, but here is a quick summary:

• Write once, use many--Don't have enough writers and have that nagging feeling you're writing what someone has already covered elsewhere?
• Edit once, fix many--For all you smarty pants who said "Cut and paste does the same thing" above.
• Write once, output many--Help in a chm and User Guide in a PDF? Using RoboHelp and FrameMaker?
• Get it right, keep it right--Have a legally tricky warning or a product name that must be used "just so?"
• Translate...once--No matter how many times and places it gets used!

The ontology of reuse

After I got my PhD, I promised myself I would use that word once a year. Ontology seeks to determine what entities can be said to "exist" and how these entities can be grouped according to similarities and differences (thank you, Wikipedia). In essence, then, our first question as architects is "What stuff can be reused?"

In DITA the central component of reuse is the topic. A topic is a self-contained bit of prose and is typically saved as a single file. Infomappers can relate a DITA topic to an information map, although it is not a common practice to save an information map as a discrete file. Information maps often get aggregated into chapters or a chm before being saved as a file.

Moving up the ontology chain, discrete DITA topics can be grouped by a defining file called a ditamap. Ditamaps can arrange DITA topics and even other ditamaps into coherent documents or sections of documents. Because a ditamap is a discrete file, it can be easily reused in multiple contexts.

Moving down the ontology chain, any component smaller than a topic can be reused if that component can be identified as a discrete component and given a distinctive ID. For example, a bulleted list exists within an html tag of "ul" so that is a potentially reusable component that can be snatched out of its topic and used elsewhere. Because XML is a semantic tagging architecture, XML documents lend themselves to very granular instances of reuse. You like that alert and want to use it elsewhere? Tag it, ID it and it's yours literally for the taking.

Next blog I will talk about some techniques and guidelines for reuse, and then we can move on to how to plan for reuse as architects.

A couple of final words on Excel

Excel

My latest column on UXmatters documents many of the procedures and tricks I have discussed here, plus it includes some useful examples and screen shots. I will also be demonstrating how to build and use an Excel-based Information Model at the STC-Atlanta August 19 meeting as part of a progression on project management.

I will also show how to use pivot tables at that meeting. Pivot tables rock!

Research and the value of iterative feedback

I just wrapped up teaching a research course at Southern Polytechnic State University. Students did their presentations last night and I was delighted! They had chosen real problems at work and used their projects to make data-driven decisions. What was interesting was how many of them had found that the data they collected and analyzed challenged their initial assumptions and biases. It was also my first opportunity to use the book I wrote with George Hayhoe. The course was on an abbreviated 8 week summer session schedule, and I was expecting the worst. Major assignments were due each week, such as proposals, annotated bibliographies, data analysis exercises, and sample surveys. But I used a teaching technique I have used before, and that is to allow multiple resubmissions of assignments until the students get it right, and then give them full credit when they do. It's not unlike my barbecue technique: Turn early; turn often. In both cases that approach has reduced the instances of burned meat and failed students. I wish I had used it when I was a people-manager. Errors and misunderstandings should be anticipated as the norm and viewed as coaching opportunities, not as aberrations to be punished.

And that's how we should use the Excel Information Model. It's not about "how did we get here (and whose fault is it)?" It's about "Where are we and what do we still have left?"

At any rate, congratulations to my students for all their hard work and the excellent results they got.