Content strategy for foodies
Content is like food. At its best, it’s a carefully choreographed experience, like dining at a fine restaurant.
Structured content
The Tech Comm Manifesto
My life in technical communication would be much easier if we all subscribed to these rules:
Interview with a vampire: interviewing to find processes that drain efficiency
When you’re considering an overhaul of your publishing workflow, you may find yourself becoming a metaphorical version of Van Helsing, the vampire-hunting character from Bram Stoker’s Dracula (and the many, many movies based on the Dracula story). You need to find all the efficiency-draining aspects of your current process and eliminate them.
The state of structure in technical communication
In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.
Some Friday fun: tech writing in movies
Here’s a movie montage I found on YouTube featuring scenes of characters either offering or reading procedures:
Enjoy!
The good manager litmus test: process change
For Kai Weber, a good manager is pivotal in making a job satisfying:
It’s the single most important factor in my satisfaction with a job. Nothing else shapes my memory and my judgment of a past job as much.
What really tests the mettle of a manager is how he or she handles process change. A good manager is absolutely critical when a documentation department switches to new authoring and publishing processes, particularly when moving from a desktop publishing environment to an XML-based one. Without good management, the implementation of new processes will likely fail. (I’ve seen bad management kill an implementation, and it’s ugly.)
So, what does a good manager do to ensure a smooth(er) transition? From my point of view, they will take the following actions (and this list is by no means all encompassing):
- Demonstrate the value of the change to both upper management and those in the trenches. A manager can often get the approval from upper management on a workflow change by showing cost savings in localization expenses, for example; (less) money talks to those higher up on the corporate chain. But mentions of reduced costs don’t usually warm the hearts of those who are doing the work. A good manager should show team members how the new process eliminates manual drudgery that everyone hates, explain how authors can focus more on writing good content instead of on secondary tasks (such as formatting), and so on. Demonstrating how the team’s work experience improves is more important than showing improvements in the bottom line—even though the cost savings are a result of those very changes. There is also the angle of professional development for a staff moving to a new environment; more on that in the next bullet.
- Ensure those working in the new process understand the new tools and technologies by offering training/knowledge transfer. A good manager knows that changing processes and not including some sort of training as part of the transition is foolish; knowledge transfer should be part of the project cost. Sure, not all companies can afford formal classroom training, but there are less expensive options to consider. Web-based training is very cost effective, particularly when team members are geographically dispersed. Another option is training one or two team members and then having them share their expertise with the rest of the group (“train the trainer”). The benefits of knowledge transfer are two-fold: team members can ramp up on the new processes in less time (thereby more quickly achieving the cost savings that upper management likes so much), and the team members themselves gain new skills in their profession. A good manager recognizes that training benefits both the company as a whole and individual employees (and he or she can help team members recognize how they benefit in the long term professionally from learning new skills).
- Know the difference between staff members who are bringing up legitimate issues with the new workflow and those who are being recalcitrant just to maintain the status quo. During periods of change, a manager will get pushback from staff. That’s a given. However, that pushback is a very healthy thing because it can point out deficiencies in the new process. A good manager will take feedback, consider it, and modify the process when there are weaknesses. Addressing genuine feedback in such a manner can also help a manager win “converts” to the new process. However, there may be an employee (or two) who won’t be receptive to change, regardless of how well the manager has explained the change, how much training is offered, and so on. In these cases, the manager may need to consider other assignments for that employee: for example, maintaining legacy documentation in the old system, particularly when that employee’s domain knowledge is too important to lose. There are more unpleasant options (including termination) the manager may need to consider if the recalcitrant team member isn’t providing other value to the organization as a whole. Basically, a good manager won’t let one individual poison the working environment for everyone else.
I will be the first to say that these tasks are not easy, particularly dealing with an employee who is utterly against change. But managers need to address all of the preceding issues to ensure a smooth transition and to keep the work environment positive and productive for the staff as a whole.
I won’t even pretend I have covered all the issues managers need to address when a department changes workflows, and each company will face its own particular challenges because of differences in corporate culture, and so on. If you’ve been through a workflow transition, please share your experiences in the comments: I’d love to hear from both managers and team members on what worked well (and what didn’t) in how management handled the changes.
PS: You can read a more detailed discussion about managing process change in our white paper, Managing implementation of structured authoring (HTML and PDF).
Managing implementation of structured authoring
An updated version of this white paper is in Content Strategy 101. Read the entire book free online, or download the free EPUB edition.
Moving a desktop publishing–based workgroup into structured authoring requires authors to master new concepts, such as hierarchical content organization, information chunking with elements, and metadata labeling with attributes. In addition to these technical challenges, the implementation itself presents significant difficulties. This paper describes Scriptorium Publishing’s methodology for implementing structured authoring environments. This document is intended primarily as a roadmap for our clients, but it could be used as a starting point for any implementation.
The State of Structure
In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.
Of the 616 responses:
- 29 percent of respondents indicated that they had already implemented structured authoring.
- 16 percent indicated that they do not plan to implement structured authoring.
- 14 percent were in the process of implementing structured authoring.
- 20 percent were planning to do so.
- 21 percent were considering it.
This report summarizes our findings on topics including the reasons for implementing structure, the adoption rate for DITA and other standards, and the selection of authoring tools.
Download 
(2 MB, 56 pages)
Discuss this document in our forum
Angst and authority
Clay Shirky has a fascinating post on the concept of algorithmic authority; the idea that large systems, such as Google PageRank or Wikipedia have authority (that is, credibility) because of the way that the system works. In other words, a page that is returned first in a Google search is assumed by the searcher to be more credible because it is ranked first.
That made me think about authority in technical content.
As an in-house technical writer, your words have authority and your content carries the corporate logo. But although this should theoretically increase your credibility, it seems that the reverse is true. Consider, for instance, the following hypothetical book titles:
- XYZ User’s Guide—This document, produced by the makers of XYZ, is shipped in the product box (or downloaded as a PDF with the software)
- XYZ Classroom in a Book—This document is available in bookstores and is produced by XYZ Press
- XYZ: The Complete Reference*—This document is available in bookstores and is produced by a third-party publisher
Which of these books would you turn to for help? What are your expectations of each document?
I believe that credibility and thus authority increases with distance from the product’s maker. In other words, the third-party book has more authority than either of the other two. Credibility is compromised by close association with the organization that makes the product.
When we apply this concept to information on the web, the implications are troubling for professional content creators who work inside corporations. If corporate authorship decreases authority, we get this result:
online help < user forums on corporate site < user forums on third-party site
Will people looking for user assistance gravitate toward independent third-party sites? What does that mean for in-house authors? How can you increase your credibility as a corporate technical communicator?
* Feel free to substitute your favorite book series title: XYZ for Dummies, XYZ: The Missing Manual, The Complete Idiot’s Guide to XYZ, XYZ Annoyances, …. I should probably also mention that I have written both a Dummies book and a Complete Reference.
Strategy < tactics < execution
I read Execution: The Discipline of Getting Things Done several years ago, and much of this post is based on the information in that book.
Because of a Series of Troublesome Committees, I find myself thinking about three big-picture concepts: strategy, tactics, and execution:
- Strategy is the overall plan. For example, one strategy for getting new projects at Scriptorium is to establish ourselves as experts in our chosen field.
- Tactics are specific actions to achieve the plan. Our tactics include writing articles and delivering conference presentations that buttress our claim of expertise.
- Execution is what happens after you pick a strategy and develop some tactics. That’s when we write the articles and attend the conferences.
Each of these stages is a prerequisite for the other. That is, you start by developing a strategy and can then pick your tactics. Finally, you have to execute on the plan.
You can fail at every point in the process:
- Choose the wrong strategy, and not much else matters. Great tactics and excellent execution will not rescue you if you have chosen the wrong approach.
- If you have the right strategy, but the wrong tactics, you may have some limited success, but poor tactics will work against you.
- Worst of all, though, is bad execution. You pick the right strategy and the right tactics, and then sabotage the whole thing with poor follow-through or lousy performance. For example, writing an article full of bad grammar or delivering a boring, technically inaccurate presentation would be bad execution for us.
At every stage, you face constraints. For instance, if your budget is limited, you might not be able to justify the most expensive tactic, even though it might have been the most effective. But once you work through your constraints and choose your tactics, there’s really no excuse for doing those activities badly.
Some things to keep in mind when working with technical communicators:
- Forget the spin. Exorcising marketing and PR messages from technical content is a core job skill for many of us. Simple, honest, and straightforward messages are better. If you try to spin your message, expect a scornful response.
- Language matters. Writers become writers because they care about language. If you want their respect, you need to show that you also care about language. At a minimum, grammar and mechanics need to be accurate. If you can go beyond the basics and demonstrate graceful writing, you will score bonus points.
In defense of English majors: we can understand business issues, too
In his latest blog entry, Neil Perlin explains how important it is for technical writers to have an understanding of business issues. With such knowledge, they can contribute to cost justifications for decisions that affect them directly. I couldn’t agree more with that. It is absolutely in writers’ best interests (and a matter of self-preservation) to understand processes and costs.
I strongly disagree, however, with the following assertion:
Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions.
I am an English major, and I freely admit I am more of a “words” person than a “numbers” person. That being said, I am no slouch in the finance department. (Calculus is another matter, though.) I know many people with degrees in English and the liberal arts who are quite adept at understanding The Big Picture and developing business cases. Lumping all of us into a “can rarely discuss cost-justification” group is unfair.
Now I need to remind myself not to group software developers into a “can rarely write a coherent procedure” category. (It’s easy to make generalizations when you’re not the target of them.)
Authoring tools do matter
“I can write in anything.”
“The tool doesn’t matter.”
“I can learn any new tool.”
Most of the time, I agree. But then, there are the exceptions.
One of our customers is using FrameMaker to produce content that is delivered in HTML. (They use structured FrameMaker, generate XML, and then transform via XSLT into HTML.) Their rationale for using FrameMaker was:
- The project was on an extreme deadline.
- The writers already knew FrameMaker.
- FrameMaker is already installed on the writers’ systems.
All valid points.
But.
We have had a continuous stream of requests from the writers to make adjustments to the FrameMaker formatting. Things like “the bullets seem a little too far from the text; can you move them over?”
FrameMaker is being used as an authoring tool only. FrameMaker formatting is discarded on export; HTML formatting is controlled mainly by CSS. However, even after repeated explanations, we continue to receive requests to modify the FrameMaker formatting.
In this specific case, the authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.
Why are they focused on this stuff? Because they can. It seems to me that moving authors to a WYSIOO (what you see is one option) tool, such as oXygen or XMetaL, instead of a WYSIWYG tool (FrameMaker) would eliminate the obsession with irrelevant formatting.
This is the future of technical communication
First, read this article in the New York Times about the struggle to keep a reporter’s kidnapping quiet:
For seven months, The New York Times managed to keep out of the news the fact that one of its reporters, David Rohde, had been kidnapped by the Taliban. But that was pretty straightforward compared with keeping it off Wikipedia.
Now, think about these issues as applied to technical communication. Let’s assume that your organization has online community — forums and a wiki, maybe. Technical communicators are responsible for monitoring and managing the community. Under what circumstances do you delete information? How do you respond when:
- Information is inaccurate
- Information is unflattering
- Both
What if the information is accurate but incomplete?
What if someone describes a way of using your product that could cause injury, even though it’s technically possible? Do you delete the information? Do you add a comment warning of possible injury? What if the reader sees the original post but not the comment?
In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you’ve done with brackets. For example:
I like riding my scooter down mountains, especially without guardrails. Wheee! [This is a really bad idea because You Might Die. -moderator]
or
I like [really bad idea redacted by moderator]. Wheee!
Deleting unflattering (but accurate) information will probably backfire on the organization. Instead of censoring negative content, try addressing the concern being identified. Think of an impolite forum post as customer feedback. Does the poster have a valid point? Can you fix the problem that’s been identified?
I hate your scooters. They don’t come in enough colors. And they suck.
What colors would you like to see? We do have two dozen available, see this list.
– Joe in TechComm
The life-or-death issues around Mr. Rohde’s kidnapping are relatively straightforward. We are likely to have much more difficult judgment calls in typical technical communication. Imagine, for example, that information were being suppressed because it criticized security arrangements and not because of safety concerns for the reporter. In that case, I think we can agree that Wikipedia’s response would have (and should have) been different. What would an equivalent scenario look like in your organization?
Building efficient multilingual workflows
STC Intercom, April 2009
A common argument for XML-based workflows is that they automate production and localization tasks. With XML, localization can be reduced to a fraction of its original cost, but how exactly does that happen?
Sarah explores automization in localization and two technology standards used in multilingual workflows: The Extensible Stylesheet Language (XSL) and XML Localization Interchange File Format (XLIFF).
Download the PDF 
(125 K)
What do Tech Writers Want?
Answer? I don’t know, but The Content Wrangler is conducting a survey to find out. Here’s the announcement:
2009 is a touch economic year for most of us. Companies are cutting back on nice-to-have purchases and focusing in on what’s necessary. This survey conducted by The Content Wrangler aims to help us better understand your training needs for 2009 and to identify the types of classes you need. We plan to use this information to help training providers create relevant public and on-site training programs that address your needs and to gain an understanding of the current state of training program interest in our industry today.
In case you need further motivation, there is also a random drawing for some goodies. The survey has only five questions, so it should be quick.
DITA isn’t magic
The WritePoint staff blog makes a very good point about DITA: it isn’t a magic wand that fixes documentation problems. Also, it’s worth noting that:
… DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s.
Don’t get me wrong: DITA can be a good solution for many departments that want to set up an XML-based single-sourcing environment. Just don’t expect that a twitch of your nose will convert your legacy content or make the output from the Open Toolkit match your formatting requirements.
The Golden Rule of technical writing
I stumbled upon a list of tips for technical writers, and I was glad to see tip 7:
Understand Your Target Audience. Write and revise your content according to how your target audience thinks and understands things. Getting into their heads–knowing how their minds process information, how they might react, what they feel is important–allows you to customize your content to tailor-fit their needs.
I would put that tip at the top of the list, but that’s a quibble.
Sarah and I mention the topic of audience a lot in our Technical Writing 101 book; I think it is the most important thing for writers to remember as they create content. You can have an elegant XML-based publishing system that generates all sorts of output with the push of a button, but if your information doesn’t address the needs of users, all the work put into the content and into the process itself is wasted.
That waste becomes even more acutely painful when a user abandons your information and finds helpful content on a blog, wiki, or forum. The contributors of that information probably don’t know (or even care) that they followed the Golden Rule of technical documentation: Audience, audience, audience.
WritersUA: DITA pilot techniques
Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.
Content creation isn’t just for tech writers
We’ve seen an increase in the number of clients who need documentation processes that include input from part-time contributors (particularly engineers). XML-based workflows make it easier to handle this sort of input. Part-time contributors can enter their information into forms or can edit XML documents in an editor that doesn’t require them to know a thing about publishing tools.
UC Irvine seems to have picked up on this trend in collaboration: the school’s extension program just announced a technical writing class for engineers:
“This course is designed to provide students with writing skills tailored for the science and engineering fields and to correct common problems,” said Jessica Scully, M.J., instructor of the course. “It covers the importance of writing for a particular audience, and applies journalism skills to help students effectively create a focused and concise document.”
The benefits of such a program go beyond engineering. Improvement in the quality of developers’ writing would likely mean a reduction in the cost of creating a more unified voice in content (which in turn would lead to a smoother localization process). And last but not least, the end users (internal or external) would get better documentation.
This class could also help engineers gain an appreciation of the skill sets technical writers bring to an organization. That being said, it would be unfortunate if a company made the short-sighted mistake of thinking that sending engineers to a class like this would transform them into instant technical communicators.
When is XML the wrong answer?
Originally published in STC Intercom, November 2007
XML can benefit a publishing workflow in many ways: improving content reuse, consistency, and potentially automating much of the process. That all sounds wonderful, but XML is not the logical answer for everyone.
Implementing a structured authoring solution requires a significant change from the familiar desktop publishing routine to new tools, technologies, and processes. Switching to XML is going to cost time and money. Depending on your needs, it may not be the most efficient solution.
The Age of … Expertise?
Over on O’Reilly’s Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:
[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?The answer is expertise. Because most activities offering a good return on investment require some rule-breaking–some challenge to assumptions, some paradigm shift–everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.
What comes after the information age? (be sure to read the comments, too)
It’s an interesting idea, but I don’t think we’re getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.
In the comments, Tim O’Reilly points out that the real change is in how information is gathered and distributed with “the rise of new forms of computer mediated aggregators and new forms of collective curation and communication.”
I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it’s helpful to look at communication dimensions:
- Traditional technical writing is one-to-many. One person/team writes, many people consume it.
- Wikis are many-to-many. Many people write; many people use the information.
- Mailing lists are many-to-one. Many people respond to one persons’ question.
- Technical support is one-to-one. One person calls; one person responds.
Technical support is the most expensive option; it’s also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.
Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos’s recent article on wikis. Then, be sure to read Anne Gentle’s eponymous rebuttal on The Content Wrangler.
Keep in mind, though, that you can’t stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it’s possible that the “unauthorized” information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.
Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?
Why XML and structured authoring is a tough transition
Found on technicalwriter’s blog:
There are several applications that incorporate features for DITA use, such as XMetal and Altova Authentic, but how much value do they provide? (Looking over the online documentation for XMetal, you will see some pretty shaky formatting and copyfitting.)
There may well be formatting and copyfitting issues. Wouldn’t surprise me at all. But talk about missing the forest for the trees!
DITA/XML/structured authoring are important because they improve how information is stored. To question their value because somebody produced documentation using them that doesn’t look so great…let’s try an analogy:
Last week, I went to a restaurant and the food was terrible. I looked in the kitchen and saw Calphalon pots and pans. I conclude that you should not buy Calphalon because the food they produce is terrible.
The quality of your food is determined by things such as the quality of the ingredients and the skill of the chef. The pan you choose does contribute — it helps to use the right size and a high-quality pan, but to dismiss DITA because one example doesn’t look quite right is pretty much like dismissing Calphalon because somebody once cooked something that didn’t taste very good in it.
PS I like Calphalon. And I have produced my share of problematic entrees.
PPS DITA is not right for everybody.
Your beautiful life
I just installed a wireless mouse on my PC here in the office. The instructions that came with the mouse have some interesting turns of phrase, including this gem:
[The mouse] combines with 27MH RF wireless technology, user-defined keys, and outstanding design, so that you can use it freely to improve your efficiency and enjoy your beautiful life from the high technology.
Yes, I often enjoy my beautiful life with high technology. Don’t you?
Authoring styles and art
Norm Walsh tackles topic-oriented authoring and makes a comparison to art.
Imagine that instead of authors, we were painters. In the narrative style, a painter (or perhaps a group of painters) begins at one side of the canvas and paints it from beginning to end (from left-to-right and top-to-bottom). They may not paint it in a strictly linear fashion, but the whole canvas (the narrative whole) is always clearly in view.
Interesting point, and he uses an image of a Vincent Van Gogh painting, chopped into unattractive bits to illustrate what goes wrong in topic-oriented authoring. The flow of the picture is lost.
But what if your content more closely resembles something by Mondrian?
Writing useful technical documentation is really, really hard. Using a narrative flow makes it a little easier to ensure that you’ve got the big picture — missing information jumps out at you just as Norm’s chopped-up painting shows.
But topic-based authoring has advantages, too.
Do you need those connections from piece to piece or can individual parts stand on their own?
Are your documents Mondrian or Van Gogh?
I hope for your sake that the product you’re documenting does not resemble Jackson Pollock‘s work.
