Errors and Humanity

A recent article by Scott Abel on Content Wrangler about TEAL, a group whose quest is to correct the typographic errors of others, got me thinking about errors. That vector is intersecting with some reading I've been doing lately in "Orality and Literacy" by Walter Ong (at the suggestion of someone to one of my earlier blogs).

First of all, we sometimes misuse the word "typo" as in typographical error. According to Wikipedia, "A typographical error or typo is a mistake made during, originally, the manual type-setting (typography) of printed material, or more recently, the typing process. The term includes errors due to mechanical failure or slips of the hand or finger, but excludes errors of ignorance." Checking other dictionaries supports that definition.

The mistake discussed in the Content Wrangler article failed to meet these criteria on two counts: (1) The mistake occurred in a hand-written sign, which would make it a chirographic error and (2) It was not a mechanical slip; it was a mistake in applying the apostrophe rule.

Scott and I had a fun discussion and I'm not blogging to belabor my point; it's just that I have a genuine interest in the different ways we make mistakes and would like to explore it a bit--not sure this will go anywhere useful. Here's my starting taxonomy:

• Typographical--More or less mechanical slips such as wrong letters or metatheses, such as my habitual typing of "form" when I mean "from."
• Oral--Where we use homonyms inadvertently, such as "there" for "their" or "too" for "two." Almost a mechanical slip, but not really, and one not caused by ignorance but rather by the hasty grabbing by our mind of a spelling from the wrong box but one located near the correct box. I also include subject/verb disagreements caused by singular words that sound plural, such as "My interest in this area are clear."
• Drops--Where a word that was in the writer's head just never makes it to the page, e.g., "I've been meaning write you..." I think this is caused by the writer's thoughts getting ahead of his fingers. It's often missed in rereading because of the Gestalt of filling in blanks based on knowing the broader context.
  
• Spelling--No accident, the writer didn't know the correct spelling.
• Punctuation--No accident, the writer thought there should be a comma and there really should not have been.
• Grammar--Breaking the rules that define conjugation and inflection.
• Usage--Wrong word for the context, such as , uh, typo to describe a punctuation mistake on a hand-written sign (OK, I am belaboring the point).
• Factual--What the writer said can be refuted by evidence or authoritative sources, e.g., "There are 51 states in the US."
• Logical--The structure of the discourse and the premises do not support a conclusion.
  

The last three--usage, factual, and logical--are major errors because they lead to miscommunication. When the others do not miscommunicate (and sometimes they do), they are minor infractions that might reflect badly on the writer but do not mislead the reader.

I think people worry too much about the minor infractions in instant messages and blogs. How often do we get an IM with a typo or oral only to get an immediate follow up like "oops, I meant two not too :-0 " Personally I think the error is part of the oral nature of IMs and the correction does more harm by interrupting the flow of the otherwise spontaneous conversation. In my comment to Scott's article I wrote "technical communicators at their worse." Oops , I know it should have been "worst" but that's the nature of a free and spontaneous engagement using language.

I'm not advocating that we get lax in our own standards, particularly as they apply to our professional, written communications. But let's be more forgiving of these patterns (yes, that's what they are, more so than mistakes) when they occur with others. Just because a restaurant can't get the menu right, doesn't mean they can't cook. Put the red pen away and enjoy your meal.

Cognitive Tools

Tom Johnson has a post on one of my favorite topics, Tools. It's not that I'm a tool fanatic, it's just that I'm fascinated by how they interact with our creativity to shape the products we make. I've long been an advocate that teaching technical communication without teaching tools is like teaching art students about painting without talking about brushes.

An aspect of tool use and evaluation that sometimes gets overlooked in tool discussions is to what degree a tool helps the user think better. The academic phrase for tools that do this is cognitive tools. Cognitive tools are closely related to performance support tools, but I draw the following distinctions:

• A performance support tool manages workflow and pushes data to the user based on the programmed expertise about the job domain the tool is programmed to support. A troubleshooting script is a performance support tool. I can use it to solve my problem but not get any smarter about troubleshooting.
• A cognitive tool helps me think about the problem space or job domain.

Whereas a performance support tool typically answers questions I ask, a cognitive tool helps me come up with questions I would have never thought to ask. Performance support tools help me do; cognitive tools help me understand.

I like tools that have a bit of both. For example, a word processor is typically a performance support tool. It lets me enter and edit text efficiently. But I often switch into Outline mode partway into writing a document and look at just my headings. All of a sudden I can see structural flaws or problems with flow that I had not noticed while immersed in the content. I can then shift topics around until I see a structure that feels right. It is the tool's ability to tap into my intuitive processes that gives it a value above its ability to enter, copy, paste, and spell-check.

Now that I am sensitive to this intuition support aspect, I am seeing all kinds of examples. Watch the video embedded in a blog about the future of the Web to see how faceted metadata searches can tap into an intuitive need to understand more but when you can't articulate the question. Warning: the initial example assumes that the reader has a well articulated question, but watch later examples as the tool helps a vision of possible relationships emerge.

Pivot tables in Excel (or pilot data tables in Symphony) have the same ability to let me kind of "poke around" in the data until I stumble on interesting relationships I had not thought to inquire about.

Ours is a very rational culture that holds a strong belief that good documents start with a clear outline, good training starts with crisp objectives, and good design starts with exhaustive requirements.

I think real projects start with some unstructured poking around that eventually converges on a clear vision of what needs to be done. Furthermore, a goodly portion of that poking around has to be done in production mode (including production tools).

So I would add a criterion to evaluating tools: Do they support cognitive activities such as analysis and relationship modeling; specifically, can they support "what if" experiments that are easily reversed if they go nowhere useful and on the other hand can be easily implemented into the production model if they prove useful.

Why I Hate PDFs

Not all PDFs; that would be over the top. I just hate user manuals that are distributed as PDFs.

1. They are mainly used online so why the artificial page constraints? I'm in the middle of a topic and all of a sudden there is a page break--not because of a topical shift but because had it been printed on 8.5 x 11 we would have run out of paper. News flash: I didn't print it and I was not running out of paper.
2. Don't hand me that "search online and then print what you want to read malarkey." If that was the plan, there would be only one set of page numbers, not a "paper" page number and an "electronic" page number that make me guess which one the printer dialog box is asking for. I know you can match them up, but most writers don't; it violates "good book design" to start counting at the beginning. That's why we all know that if the page number is a Roman numeral, there is no useful content on that page.
3. They are laid out as if they were going to be printed--and printed in duplex at that! If the company is too cheap to print, then at least make it easy for Joe Schmoe to print and stop with the recto/verso page layouts.
4. They carry so much book overhead: book front cover pages, book back cover pages, inside cover pages, chapter cover pages. It takes me three clicks to get to a topic that actually says something.
5. There are too many of them and they are named after obscure roles--none of which describe me. I've never met a system administrator, never saw the job title anywhere I worked, yet there are a bazzilion guides out there written for that person. I always suspect that what I need is scattered across three different guides. Give me a single source where I can ask my question once and get all my possible results.
6. They just scream, "Books are what I know how to write; books are what you get."

User books died; if they had value in that form, companies would still print them and users would buy them. Yet PDFs still hang around like pathetic home town sports fans after the team has moved to the West Coast. Quintus in The Gladiator says "A people ought to know when they've been defeated." PDFs should get the wake-up call.

[Yes, I quoted The Gladiator. It's one of my favorite movies; you might want to take that into consideration when deciding how much credibility to give my opinions.]

Same Topic, Different Content

The last area of reuse is where a topic could be reused if certain snippets could be changed. Most of us know this as conditional text; DITA I believe calls it conditional processing. I'm not a tech comm historian, but I would wager that this is the oldest implementaion of reuse other than copy and paste.

The most common applications are where some snippet, phrase, or instruction would be different depending on the OS or reader role. For example, have an instruction say ,"Click Start > Shutdown" for the Windows version of a manual and for Mac say, "Oh get over yourselves." (Sorry, couldn't resist that one.)

In DITA, you do this with ditaval properties and a separate .ditaval file that implements the conditionality when the ditamap processes the document. The main tip I have on that is to comment in the ditamap what ditaval files to run for what conditions. Sometimes we forget that others must follow us and will need the path blazed (also, when we come back to that file 12 months later we won't have the foggiest idea what we did).

Conditional text can let you get a lot of reuse out of instructions that have slightly different commands within a few steps. It can become a slippery slope, however, that can take you from writer to programmer if you're not careful. I have heard of some conditional strings in that no one could untangle after the original author ever left. The conditional text was trying to deal with multiple products and multiple audiences at the same time, or something like that, I believe. It certainly made editing and testing a challenge as well.

This ends my series of blogs on reuse. It's been helpful for me to reflect; thank you for your patience.

I made this joke up

An editor, a tech comm manager, a professor of technical communication, and a techical writer go into a bar. The bartender asks, "What are you having?"

The editor says, "At the moment nothing."

The manager asks, "What do you have?"

The professor asks, "What are others having?"

The tech writer says, "<step><cmd>Give me a <uicontrol>beer</uicontrol></cmd></step>"

Same Content in Many Topics

That last side trip about which voice to use still has my head woozy and so I need to get grounded again by talking about reuse.

Reusing snippets

Another scenario in reuse is where the unit of reuse is smaller than an entire topic. Common examples include:

• Product names
• Notes, Warnings, and Cautions
• Descriptions of common user actions
• Any sensitive text that has been vetted

There are several advantages to reuse in the case of snippets like these:

• Creative productivity--By this I mean not having to make up text time and time again. I differentiate this from productivity gains from not having to type the same text time and time again, because I'm not convinced that it takes less time to insert a cross reference than it would take to type it anew. The savings, in my mind, come from not having to recompose it each time.
• Revision efficiency--Oh yeah, when marketing decides the product is now WormBuster XL rather than WormBreaker: edit once, change many.
• Control--After two hours of arguing with legal and marketing how to warn the user that changing advanced parameters could crash their system if they make a typo, make sure that the vetted text is used everywhere.
• Consistency--If the drop down for selecting port protocol on this screen works just the same way as it works on 11 other screens, it is easier for the user to process and remember the instruction if it is the same for all 12 screens.

Guidelines

To reuse subtopic elements, you need a composition environment that allows you to identify components and insert them in topics as objects. In DITA, this is easy since DITA is a semantic markup XML implementation. Every tag has an ID attribute, so every element that can be tagged can be IDed and subsequently shared. The tag in DITA that allows you to insert content from another topic is called the content reference [conref]. Essentially it is a tag in one file that points to a tag in another file.

Ubiquity

The big caveat in DITA, however, is to use ubiquitous tags, that is, elements that can be used the most widely within the rules of the DTD (the rule-keeper of structured writing, essentially the defining document that says what can be used where).

For example, all DITA topics have a short description [shortdesc], but a topic can have only one [shortdesc]This means that if you want to reuse that short description elsewhere, you must give it a tag other than [shortdesc]. The phrase tag comes in handy there. You would tag your short description like this:

[shortdesc][ph id=sort_search]Use this dialog box to sort the order of your search results.[/ph][/shortdesc]

That way, you can grab that phrase and reuse it in other topics, even as the short description in other topics.

Corral your sources

A good practice is to create special files that contain your conref'ed phases or components. That way you do not have to go looking for them trying to remember what topic was the source of that well-phrased warning. It is useful to have specialized conref files, for example, a file for product names, a file for warnings and alerts, a file for UI components, etc.

Probably the best practice in this regard is to develop the discipline that the first time you decide to conref a phrase that you have already used in a topic, pull that phrase out of its original topic, put it in a conref source file, then conref it back into the original as well as the new topic. Not only does this preserve the integrity of single sourcing, it lets you rethink how you want to word that element now that you are throwing it into the reuse pool for others.

Avoid restrictive wording

This is pretty much the same guideline that we had for topics. Think reuse ahead of time. For example, if you are documenting a UI component that sets the source port for a firewall rule, and you know that same component is used elsewhere to define destination ports, avoid using the restrictions "source" or "destination" in the instruction. The user should pick that context up from the topics themselves, don't restrict the reuse of the instruction by repeating that restriction there.

Guess who's talking

A little side trip again away from reuse. I was visiting with my sibs in Florida and was picking up a bar tab (since I am typically the major contributor to the total). The waitress delivered me two credit card tickets, one labeled "Mine" and the other labeled "Yours."

So which one do I keep and which one do I give back to her?

Had she handed them to me and said "This one is mine and this one is yours," I would have given her the one about which she had said "This one is mine." But because it was in writing, I was inclined to keep the one that said "Mine." I guess because as I read it, the voice in my head was my voice and I identified "Mine" with me. But the "Yours" didn't work in that scenario since I wasn't talking to anyone other than myself. I think I kept "Yours" and gave her "Mine" not feeling any too comfortable that I had gotten it right.

But boy, what a lot of thinking just to figure out which to give back of two documents that would have been the same except for the label that tried to differentiate them.


Why not "Customer" and "Merchant"? like most do? That is not ambiguous.

Or even "Give us one and keep the other."

Or don't label either. Then if I asked which one she wanted she could say, "The one with the big tip on it."