Half-price sale ebooks on UX and tech comm

O’Reilly sells ebooks from the publishing group Elsevier at half price until 23 April.

I blog about it because I think this is a good deal. Also, I like O’Reilly ebooks because they are DRM-free. I am not affiliated with O’Reilly or Elsevier. I get no payment in money or in kind for writing this.

Here are some titles of interest for tech comm and UX people. So if you’ve heard about one of these titles or keep it on a list of books to check out, here’s a good opportunity.

• The info below is straight from the O’Reilly web site.
• Prices are before the discount.
• Use discount code WKESEVE to get 50% off until 23 April.

For tech comm

Designing the Search Experience
By Tony Russell-Rose, Tyler Tate
December 2012
Ebook: $39.95

Letting Go of the Words, 2nd Edition
By Janice Redish
September 2012
Ebook: $49.95

Information Visualization, 3rd Edition
By Colin Ware
May 2012
Ebook: $64.95

Content Strategy at Work
By Margot Bloomstein
January 2012
Ebook: $29.95

For UX

Designing the Search Experience
By Tony Russell-Rose, Tyler Tate
December 2012
Ebook: $39.95

Agile User Experience Design
By Diana Brown
October 2012
Ebook: $39.95

Observing the User Experience, 2nd Edition
By Mike Kuniavsky, Andrea Moed, Elizabeth Goodman
September 2012
Ebook: $59.95

Information Visualization, 3rd Edition
By Colin Ware
May 2012
Ebook: $64.95

Quantifying the User Experience
By Jeff Sauro, James R Lewis
March 2012
Ebook: $49.95

Sketching User Experiences: The Workbook
By Saul Greenberg, Sheelagh Carpendale, Nicolai Marquardt, Bill Buxton
November 2011
Ebook: $19.95

Global UX
By Whitney Quesenbery, Daniel Szuc
October 2011
Ebook: $49.95

User Experience Management
By Arnie Lund
May 2011
Ebook: $39.95

Brave NUI World
By Daniel Wigdor, Dennis Wixon
April 2011
Ebook: $39.95

Thoughts on Interaction Design, 2nd Edition
By Jon Kolko
January 2011
Ebook: $29.95

Usability Testing Essentials
By Carol M. Barnum
October 2010
Ebook: $49.95

Smart Things: Ubiquitous Computing User Experience Design
By Mike Kuniavsky
September 2010
Ebook: $41.95

Sketching User Experiences: Getting the Design Right and the Right Design
By Bill Buxton
July 2010
Ebook: $49.95

Measuring the User Experience
By Thomas Tullis, William Albert
July 2010
Ebook: $53.95

Visual Thinking
By Colin Ware
July 2010
Ebook: $45.95

User-Centered Design Stories
By Carol Righi, Janice James
July 2010
Ebook: $69.95

The Essential Persona Lifecycle: Your Guide to Building and Using Personas
By Tamara Adlin, John Pruitt
March 2010
Ebook: $31.95

Advertisement

DITA with confidence (DITA Best Practices book review)

I recommend DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt to anyone who looks for practical guidance with DITA or topic-based writing with a future DITA option. (This book review has appeared in the Summer 2012 issue of ISTC’s Communicator magazine on p. 57 in different format.)

The DITA bookshelf has been growing slowly but surely. Thanks to the recent addition of the seminal DITA Best Practices, you can now find most information you need for a DITA implementation project in one book or the other.

The paperback comes from IBM Press which has also given technical writers Developing Quality Technical Information by Gretchen Hargis, et al. If you know that recommended title, you will enjoy the same usefulness and clear layout in this new book.

Starting with topics

DITA Best Practices addresses the practical concerns of writers, editors and architects of DITA content in three well-structured parts. The first part on writing starts with a chapter on topic-based writing and task orientation as two methods underlying DITA. The authors give clear instructions and guidelines for both methods. A generous amount of tips, best practices and ‘watch out’ warnings add the voice of the experienced practitioner which help to keep you on track or avoid beginner’s mistakes. The fictional ‘Exprezzoh 9000N’ coffeemaker is used consistently throughout the book to illustrate tasks and topics. Explanations why and how the methods work give writers the motivation to apply the advice with confidence. The chapter ends with a concise wrap-up section of the big points and a checklist to ensure you apply these big points in your work.

I have outlined the first chapter in such detail, because its clear and competent combination of elements — instructions, tips and warnings, examples, motivation, wrap-up and checklists — make this book so useful throughout.

One chapter each is then dedicated to topic types task, concept and reference. Each chapter describes the characteristics and motivation for the topic type, followed by instructions and examples along the standard DITA topic structure. The task chapter, for example, proceeds from <title> via <shortdesc>, <context>, <prereq> to <steps>, etc. However, most guidelines, examples, tips and warnings apply to good topic-based writing practices in general.

A chapter dedicated to DITA’s ‘short description’ element with its multiple uses in topics, links and search results helps novices with the challenge to use this powerful element correctly.

DITA’s architecture explained

The second part of the book builds on the first. After describing topics as DITA’s most essential building blocks, the book focuses on making topics work together by connecting them and by expanding their usability.

Two chapters show you how to connect topics into a coherent output, such as an online help system or a book. The first chapter on DITA maps explains how to create tables of contents, including bookmaps for print publications. The second chapter on links describes the four different ways to link topics to each other that in DITA. In their reassuring style, the authors help you to distinguish them, so you understand when to use which link type and how to apply each correctly.

The next three chapters explain how to make topics work together by expanding their usability: You can use metadata to make your topics ‘smart’ by adding information such as index terms, addressed audience or described product or version. You can use conditional processing to customise output. And you can reuse content for more consistent output and reduced translation costs. A clear workflow helps you to determine which of your content you can reuse and how.

Editing in DITA

The third part of the book deals with editing. One chapter outlines the steps and decisions of a project to convert your exiting content to DITA. Useful worksheets help you to analyse your content and prepare it for conversion. The chapter on code review helps you to avoid or eliminate common problems that restrict the benefit of your DITA code. Based on their experience, the authors remind you to use DITA topic types and elements correctly, for example, to use the <steps> element in task topics instead of a more generic ordered list. The chapter on content editing applies best practices of editing to DITA topics and maps.

Useful and recommended

Since it came out, I have used this book more than any other technical writing book, except a style guide. Had it been published earlier, it would have saved me many an uncertain moment when I was designing and teaching our information model. I especially appreciate the clarity, the concision and the well-argued advice of do’s and don’ts. For all its benefits, be aware that the book covers neither the DITA Open Toolkit nor DITA specialisations!

DITA Best Practices lives up to its subtitle and provides essential instruction and advice to technical writers, editors and information architects. Project managers will find it equally helpful but should also consider Julio Vazquez’ Practical DITA which reflects a project structure better. Decision-making managers are probably better off with Ann Rockley’s DITA 101 which gives a shorter high-level overview.

Advice about breaking into tech comm

Some time ago, a lab technician asked me how to go about breaking into technical communications. I’ve already replied to J privately, but I thought the issue could be of interest to you as well, so here’s J’s question and my reply, both edited for publication.

J wrote me:

I’ve recently become very interested in the Technical Communication field. Currently, I’m working as a lab technician for laboratory machinery which can sometimes be very difficult to operate.

I’ve been spending more and more of my time poring through technical instructions, talking to sales associates, and transcribing everything into easy-to-understand instructions to be used by my co-workers. This has expanded to the point where I break down complex laboratory procedures, peer-reviewed studies, etc. into something my co-workers can understand.

I really enjoy this sort of work and would like to make a full time career out of it. But I don’t know where to begin.

Ideally, I’d like to begin by doing this sort of writing as a freelance gig and slowly build up my business until it affords me a comfortable living.

What’s the best way to get started? Do tech comm writers typically work freelance or are they typically full-time employees for a particular company? Can you recommend any websites or books that might help me out? How do most people in the Technical Communication field make their money?

And I replied:

Hi, J,

From what you tell me, you’re on a very good way to becoming a technical communicator, for two reasons:

You focus on users. In my experience, it’s essential to have the right perspective in that job: To understand the users and to make sure they can do their jobs well. Many tech writers get bogged down by the systems they describe and their features, because they’re right in their faces. Of course, knowing these is important – but your first obligation should be to your users. They are your customers, whether they are inside your company or outside.

You have strong domain knowledge. Many tech comm’ers either have a strong writing background (and a liberal arts degree, like I do in American Studies), or they have, loosely speaking, an engineering background. You’ll find your background valuable in 3 ways:

1. You’ll need it to get respect from your peers, whether you collect information from them or ask them to review your documents.
2. You’ll gain trust from your readers/customers, when they realize you speak their language and know what you’re talking about.
3. It will help you with managers who often appreciate domain knowledge over writing skills, if only because they think that “anybody can write”.

A general disclaimer before I go on: I’m afraid I don’t know the US job market nearly good enough to offer reliable advice. I’ve gone to school in the US, and know some tech comm’ers there, but I’ve never actually worked in the US. So I can’t really advise you on the freelance vs. employed question. My impression is that it seems to be pretty difficult to go the freelance route when you’re just starting out…

That said, there are really both scenarios:

• Self-employed tech comm’ers often appreciate setting their own rates and hours and the mix of topics they cover. But it’s difficult to build a customer base that keeps paying your rent.
• Employed tech comm’ers have a regular paycheck, but many complain about being awfully low on the corporate totem pole/food chain. Unless you establish good rapport and earn respect (which is hopfully easy for you thanks to the two reasons above), you might find that many colleagues and managers don’t really understand what you do, how you add value to the company.

Two books I’ve found especially helpful are:

• Developing Quality Technical Information is good and relevant, even though it’s 7 years old. It’s basically a gigantic, well-argued check list with lots of good examples. If you only were to read a single book on tech comm, I recommend this one.
• DITA Best Practices came out about half a year ago. This is a very good book if you publish any kind of online documentation, whether you follow the DITA standard or not. Chapters 1, 2, 3, 4, 7, and 10 are about topic-based authoring, specifically about designing, writing, linking and editing topics. It’s a very instructive hands-on book with lots of examples.

Online resources are plentiful, I recommend you start with:

• Tom Johnson’s blog I’d rather be writing. He’s the most visible tech comm blogger and has been helpful in the past, answering questions about breaking into tech writing. Lately, he’s opened up a few such requests to communal answers. If you don’t get a direct answer from him, I think you’ll find his past posts and their comments helpful. Plus, he’s based in the US!
• Social networks are nicely summed up and compared in Bill Albing’s post “How social can we go”. I like ATC and TWW.
• Twitter is also a massive hangout for tech comm people. These two lists are a good start to follow us around.

I hope I could give you some ideas and helpful advice. I wish you good luck in what I think is an exciting profession!

All the best, Kai.

Is the new Microsoft Manual of Style for you?

The 4th edition of the Microsoft Manual of Style (MMoS) has been updated substantially in a few crucial areas. It’s indispensable, if you work in a Microsoft domain and worth checking out if not.

Full disclosure: I’ve received a free review copy.

The previous edition of 2004 was becoming quite dated, so a new edition was eagerly awaited by many writers. Here’s what’s new, so you can make up your mind whether you need the new edition. I’ll focus on the first half, the “General Topics” with guidelines, which has the most significant updates.

General impressions

Guidelines have been reshuffled to emphasize the book’s shift from technical publications (such as online help or user manuals) to professional technical communications (which may also appear in web sites, blogs or wikis):

• Previously, the first two chapters were dedicated to “Documenting the User Interface” with screens, dialogs, properties, etc. and to layout. So the message was: “Put proper words pretty on a page.”
• Now it’s the “Microsoft style and voice”, followed by “Content for the Web”. So the new message is: “Know your audience and adapt your sound and your channel!”

Many guidelines and examples have been carried over or edited only slightly from the previous edition, which is fine, because they still apply.

Examples have adopted a new tone: Previously, they were marked as “Correct” or “Incorrect”, now they’re labelled “Microsoft style” or “Not Microsoft style”. Ironically, this modesty is undercut by another change in the text. Previous suggestions to “avoid” certain things have become more strict and now tell you “do not use”.

Layout feels fresher throughout and easier to read. See for yourself at amazon’s Look inside preview.

The 4th edition by chapters

Ch. 1: Microsoft style and voice

A front-loaded new section presents 9 pages of “Principles of Microsoft style” along the lines of consistency, attitude, language, precision, sentence structure and grammatical choices, punctuation, contractions, and colloquialisms and idioms.

This is a welcome framework that can double as a declaration of values or truths to be held self-evident. A tech writing team I know uses the MMoS as the background for their in-house style guide – and with this new section, I guess they can get rid of some of the painfully argued standards and simply refer to this new edition.

I see this section not as a dictate by Microsoft, but as a modest proposal that’s worth considering – and discarding only with good reason. The book’s Look inside at amazon.com allows you to preview most of the chapter, so check it out to see what I’m talking about.

Ch. 2: Content for the web

This important chapter has also been rewritten and moved to the front where it has the prominent position it deserves. But to be honest, it trails several more focused, more expert works.

Still, this is now much more oriented towards useful content and starts with “Make the right content choices” and then goes on to advocate scannable, organized text with lots of links. Additional, but short sections address video, blogs, and wikis as well as task analysis, SEO and social media optimization.

So it’s now a decent attempt with helpful suggestions in the context of a style guide. If you’re at all serious about writing for an audience on the web, you will know or want some of the more expert titles.

Ch. 3: Content for a worldwide audience

This chapter has been edited and expanded, but not substantially changed from the previous chapter 3 “Global Content”. You can preview it, along with the new 2-column layout of guidelines and more information, as a sample chapter at Microsoft Press’ blog post.

Ch. 4: Accessible content

As the audience of technical communications has grown and diversified, accessibility has rightfully gained traction. So it’s a pity to see that this important topic still only gets 4 pages, and not much that’s new to boot.

This is little more than a first check list to make you aware of essential issues and remedies. You can find more in-depth information online.

Ch. 5: The user interface

This is the centerpiece of the manual – and essentially the law in what user interface stuff is called in the Microsoft universe. It’s where the new edition excels and the previous edition was most badly dated.

Much of this chapter had to be redone completely to include ribbons, smart phones, the MS Office 2010 “backstage view” (which is what the File menu section is now called that has replaced the application button). If you’re writing for any Microsoft product, including Windows, you will need this sooner or later.

Ch. 6: Procedures and technical content

This chapter has also been updated:

• Cloud computing is in.
• Guidelines for procedures, reference, XML and HTML  documentation remain.
• Standards on documenting COM and ActiveX are out.

Ch. 7: Practical issues of style

This chapter now combines parts of what used to be chapters on “Content Formatting and Layout” and “Common Style Problems”. It contains essentially unchanged information about cross references, dates, numbers, page layout, titles & headings, etc.

Ch. 8: Grammar

A welcome addition to this chapter are several “international considerations”! If you’re writing for translation or an international audience, you’ll find these tips helpful, such as:

• Avoid passive, because it translates poorly into some languages.
• Avoid imperative in marketing tag lines which comes across as dictatorial in some cultures.
• Avoid “(s)” for optional plural which translates poorly.

Ch. 9ff.

There have been few changes or updates to the remaining chapters on Punctuation, Indexes and keywords, and Acronyms and other abbreviations.

The verdict

The Microsoft Manual of Styles is a very helpful resource. It’s mainly well thought out and solves many problems, so you don’t have to.

If you write for Microsoft environments at all, you need this latest edition to stay consistent.

If you write for the web, accessibility, localization, international audiences, API/SDK documentation, you may need additional resources, either as online or print resources. The MMoS won’t – and in all fairness: can’t – deliver everything you need.

Proving the benefit of consistency in tech comm

To ensure efficiency and accessibility of technical communications, use consistent, common formatting, for example, for interface elements. What sounds obvious to many technical communicators is actually proven in academic studies. This post is for people looking for proof that consistency has a benefit in technical communications.

I’m taking my cue from a question that appeared in a LinkedIn group:

[I need to] find studies or tests that show that it is value-adding to have consistent formatting on e.g. User Interaction elements (such as buttons or handles) in your instructive documents. Can anyone share studies or tests in this area?

I can offer an answer on two levels:

• The general benefits in terms of human perception
• The particular benefits of consistent documentation

The neuroscience of consistency

Human perception favors consistency. The mind groups things easier, faster and with more confidence, if they’re consistent and have something in common.

Gestalt law of similarity: The mind groups similar elements into collective entities, from Wikipedia.

Psychological studies have shown two principles by which human perception groups things: Proximity and similarity. For a comparison of these two principles and further references, see Han, S., Song, Y., et al. (2001). Neural substrates for visual perceptual grouping in humans. Psychophysiology, 38, 926-935. Han and colleagues actually quote several studies that “proximity is a more salient cue than similarity.”

In technical comunications texts, we usually can’t practically lump all names of windows or fields across all topics together to show they’re related.

But we can resort to similarity to help readers understand that we mean a GUI element at each occurrence. If we always write their names in bold, for example, readers will recognize that similarity across topics and learn to scan for it (whether they’re aware of it or not). If we always mark up GUI elements somehow, sometimes in bold, sometimes in italics, readers are more likely to wonder if the different markup has a meaning – and they won’t be able to scan the text as quickly and reliably.

For more psychological research and how it applies to technical communications, refer to Chris Atherton‘s excellent and accessible article “What and where?” in ISTC’s Communicator quarterly, Spring 2011, pp. 28-29.

Studies of applied consistency

So much for the theory. But does consistency, for example in formatting GUI elements, have an actual benefit in documentation?

One very good resource to argue for such consistency is the Research-Based Web Design & Usability Guidelines. This 292-page tome sets out “to provide quantified, peer-reviewed Web site design guidelines”. It was published by the US Department of Health and Human Services in 2006 and is available for free download, as a book and as individual chapters.

Chapter 11 on “Text Appearance” has a couple of applicable guidelines:

#2 Format common items consistently

Common, recurring items, such as telephone numbers, time records, button and window names should be formatted consistently, according to expert recommendations in: Ahlstrom, V. & Longo, K. (2001). Human factors design guide update (Report number DOT/FAA/CT-96/01): A revision to chapter 8 – computer human interface guidelines.

#4 Ensure visual consistency

Visual consistency, including the appearance of characters in interfaces, reduces user errors. “Studies found that tasks performed on more consistent interfaces resulted in (1) a reduction in task completion times; (2) a reduction in errors; (3) an increase in user satisfaction; and (4) a reduction in learning time.” The quoted studies include:

• Adamson, P.J. & Wallace, F.L. (1997). A comparison between consistent and inconsistent graphical user interfaces. Jacksonville: University of Northern Florida, Department of Computer and Information Sciences.
• Eberts, R.E. (1997). Cognitive modeling. In: G. Salvendy (ed.), Handbook of Human Factors and Ergonomics, 2nd ed., New York: John Wiley & Sons.
• Ozok, A.A. & Salvendy, G. (2000). Measuring consistency of web page design and its effects on performance and satisfaction. Ergonomics, 43(4), 443-460.
• Schneider, W., Dumais, S.T. & Shiffrin, R.M. (1984). Automatic and control processing and attention. Varieties of Attention. New York: Academic Press, 1-27.
• Schneider, W. & Shiffrin, R.M. (1977). Controlled and automatic human information processing: detection, search and attention, Psychological Review, 84, 1-66.

Specifically, Ozok and Salvendy in 2000 confirmed the earlier studies that visually inconsistent interfaces lead users to poorer performance and more errors, see the summary in the Human Factors International newsletter.

– I hope this little field trip into academia can help you to prove that consistency not merely seems somehow desirable and logical, but has actually cognitive benefits proven in studies.

Improve documentation with quality metrics

Quality metrics for technical communication are difficult, but necessary and effective.

They are difficult because you need to define quality standards and then measure compliance with them. They are necessary because they reflect the value add to customers (which quantitative metrics usually don’t). And they are effective because they are the only way to improve your documentation in a structured way in the long run.

Define quality standards

First, define what high quality documentation means to you. A good start is the book Developing Quality Technical Information: A Handbook for Writers and Editors from which I take these generic quality characteristics for documentation topics:

• Is the topic task-oriented?
  Does it primarily reflect the user’s work environment and processes, and not primarily the product or its interface?
• Is the topic up-to-date?
  Does it reflect the current version of the product or an older version?
• Is the topic clear and consistent?
  Does it comply with your documentation style guide? If you don’t have one, consider starting from Microsoft’s Manual of Style for Technical Publications.
• Is the topic accurate and sufficient?*
  Does it correctly and sufficiently describe a concept or instruct the customer to execute a task or describe reference information?
• Is the topic well organised and well structured?*
  Does it follow an information model, if you have one, and does it link to relevant related topics?

* Measuring the last two characteristics requires at least basic understanding of topic-based authoring.

The seal of quality

You may have additional quality characteristics or different ones, depending on your industry, your customers’ expectations, etc. As you draft your definition, remember that someone will have to monitor all those characteristics for every single topic or chapter!

So I suggest you keep your quality characteristics specific enough to be measured, but still general enough so they apply to virtually every piece of your documentation. Five is probably the maximum number you can reasonably monitor.

Measure quality

The best time to measure quality is during the review process. So include your quality characteristics with your guidelines for reviewers.

If you’re lucky enough to have several reviewers for your contents, it’s usually sufficient to ask one of them to gauge quality. Choose the one who’s closest to your customers. For example, if you have a customer service rep and a developer review your topics, go with the former who’s more familiar with users’ tasks and needs.

To actually measure the quality of an online help topic or a chapter or section in a manual, ask the reviewer to use a simple 3-point scale for each of your quality characteristics:

• 0 = Quality characteristic or topic is missing.
• 1 = Quality characteristic is sort of there, but can obviously be improved.
• 2 = Quality characteristic is fairly well developed.

Now, such metrics sound awfully loose: Quality “is sort of there” or “fairly well developed”…? I suggest this for sheer pragmatic purposes: Unless you have a small number of very disciplined writers and reviewers, quality metrics are not exact science.

The benefit of metrics is relative, not absolute. They help you to gauge the big picture and improvement over time. The point of such a loose 3-point scale is to keep it efficient and to avoid arguments and getting hung up on pseudo-exactitude.

Act on quality metrics

With your quality scores, you can determine

• A score per help topic or user manual chapter
• An average score per release or user manual
• Progress per release or manual over time

Areas where scores lag behind or don’t improve over time give you a pretty clear idea about where you need to focus: You may simply need to revise a chapter. Or you may need to boost writer skills or add resources.

Remember that measuring quality during review leaves blind spots in areas where you neither write nor review. So consider doing a complete content inventory or quality assessment!

Learn more

There are several helpful resources out there:

• The mother lode of documentation quality and metrics is the book Developing Quality Technical Information by Gretchen Hargis et al. with helpful appendixes, such as
  • Quality checklist
  • Who checks which quality characteristics?
  • Quality characteristics and elements
• Five similar metrics, plus a cute duck, appear in Sarah O’Keefe’s blog post “Calculating document quality (QUACK)“
• Questionable vs. value-adding metrics are discussed in Donald LeVie’s article “Documentation Metrics: What Do You Really Want to Measure” which appeared in STC’s intercom magazine in December 2000.
• A summary and checklist from Hargis’ book is Lori Fisher’s “Nine Quality Characteristics and a Process to Check for Them”**.
• The quality metrics process is covered more thoroughly in “Quality Basics: What You Need to Know to Get Started”** by Jennifer Atkinson, et al.

** The last two articles are part of the STC Proceedings 2001 and used to be easily available via the EServer TC Library until the STC’s recent web site relaunch effectively eliminated access to years’ worth of resources. Watch this page to see if the STC decides to make them available again.

Your turn

What is your experience with quality metrics? Are they worth the extra effort over pure quantitative metrics (such as topics or pages produced per day)? Are they worth doing, even though they ignore actual customer feedback and demands as customer service reps can register? Please leave a comment.

Learn about DITA in a couple of hours

DITA 101, second edition, by Ann Rockley and others is one of the best tool-independent books about DITA. It’s a good primer to learn about DITA in a couple of hours.

Strong context

The book excels in firmly embedding DITA’s technologies and workflows in the larger contect of structured writing and topic-based authoring.

I attribute this to the authors’ years of solid experience in these areas which comes through, especially in the earlier chapters.

“The value of structure in content,” the second chapter, illustrates structured writing with the obvious example of cooking recipes. Then it goes on to show you how to deduce a common structure from three realistically different recipes – which I hadn’t seen done in such a clear and concise way.

“Reuse: Today’s best practice,” the third chapter, takes a high-level perspective. First it acknowledges organizational habits and beliefs that often prevent reuse. Then it presents good business reasons and ROI measures that show why reuse makes sense.

Comprehensive, solid coverage

From the fourth chapter on, Rockley and her co-authors describe DITA and its elements very well from various angles:

• “Topics and maps – the basic building blocks of DITA” expands on the DITA specification with clear comments and helpful examples.
• “A day in the life of a DITA author” is very valuable for writers who are part of a DITA project. Writing DITA topics and maps is fundamentally different from writing manuals, and this chapter highlights the essential changes in the authoring workflow.
• “Planning for DITA” outlines the elements and roles in a DITA implementation project for the project manager. Don’t let the rather brief discussion fool you: Without analyzing content and reuse opportunities, without a content strategy and without covering all the project roles, you expose your DITA project to unnecessary risk.
• “Calculating ROI for your DITA project” has been added for the second edition. It’s by co-author Mark Lewis, based on his earlier white papers: “DITA Metrics: Cost Metrics” and “DITA Metrics: Similarities and Savings for Conrefs and Translation“. It expands on the ROI discussion of chapter 3 and creates minor inconsistencies that weren’t eliminated in the editing process.
• “Metadata” first introduces the topic and its benefits in general and at length. Then it describes the types and usefulness of metadata in DITA. This might seem a little pedestrian, but it’s actually helpful for more conventional writers and for managers. It ensures they fully understand this part of DITA which drives much of its efficiencies and workflows.
• “DITA and technology” explains elements and features to consider when you select a DITA tool, content management system or publishing system. This always tricky to do in a book as much depends on your processes, organization and budget. While the chapter cannot substitute for good consulting, it manages to point out what you get yourself into and what to look out for.
• “The advanced stuff” and “What’s new in DITA 1.2” continue the helpful elucidation of the DITA specification with comments and examples that was begun in the “Topics and maps” chapter.

Mediocre organization

For all its useful contents, the book deserves better, clearer organization!

• Redundancies and minor inconsistencies occur as concepts are defined and discussed in several places. For example, topics are defined on pages 4, 24 and 46. The newly added ROI chapter complements the ROI points in the third chapter, but neither has cross-references to the other.
• The index doesn’t always help you to connect all the occurrences and navigate the text.
• Chapters are not numbered, yet numbering of figures in each chapter starts at 1. It’s not a big problem, because references to figures always refer to the “nearest” number, it’s just irritating.

Formal errors

The book contains several errors which add to the impression of poor production values. They don’t hurt the overall message or comprehensibility, but they are annyoing anyway:

• Mixed up illustrations such as the properties box in Word (page 72) vs. the properties box from the File Manager (73)
• Spelling errors such as “somtimes” (1) and “execeptions” (16)
• Problems with articles such as “a author” (20) and or a system that “has ability to read this metadata” (77)
• Common language mistakes such “its” instead of “it’s” (52)

Lack of competition

Another reason why it’s still one of the best books on the topic is that there simply aren’t many others!

• Practical DITA by Julio Vazquez is the only serious contender, and its practical, in-the-trenches advice complements Rockley’s book very well.
• [More books are pointed out in the comments, thanks everybody! – Added January 11, 2010.]
• DITA Open Toolkit by “editors” Lambert M. Surhone, Mariam T. Tennoe, Susan F. Henssonow is a compilation of Wikipedia articles. Amazon reviewers call other titles produced by the same editing team and publisher a scam.

Of course, several other honorable and worthwhile books include articles or chapters on DITA and/or discuss DITA in context of specific tools.

My recommendation

Despite its shortcomings, the book’s own claim is valid: “If you’re in the process of implementing DITA, expect to do so in the future, or just want to learn more about it without having to wade through technical specifications, this is the book for you.”

I recommend that you read it if you are

• Involved in a project to implement DITA
• Writing or translating documentation in a DITA environment
• Managing technical writers

Your turn

Have you read this book? What’s your opinion? Can you recommend other books or resources about DITA? Feel free to leave a comment!

TCUK10 conference videos online

Speaking of conferences, one stream of 13 presentations at the ISTC’s conference TCUK10 was recorded, and the videos are now online.

Included are the two keynotes by Nokia’s David Black and by J Haynes of Haynes manuals, as well as Roger Hart on content strategy, Chris Atherton on the psychology of usability, and many more.

The slide from J Haynes’ presentation is both, a sign and a reason of Haynes’ success. Check out the presentation to hear the story behind it.

(My own presentation wasn’t recorded, and I like to believe it’s for the better… 🙂 )

Happy holidays & a recommended read

Kai’s Tech Writing Blog takes a break for the rest of the year. I wish you a happy holiday season, and I’ll see you in early 2011.

If you’re looking for a change of pace, I can recommend a great, but short book: Paul Harding’s Pulitzer Prize-winning novel Tinkers makes for slow wonderful reading as the main character thinks back on his and his father’s life in rural New England through the 20th century.

Interspersed with the narrative are excerpts from the Rev. Kenner Davenport’s The Reasonable Horologist from 1783. This instructional text is a great example for artful and stylish documentation:

Now, the horologist looks upon an openfaced, fairy-book contraption; gears lean to and fro like a lazy machine in a dream. The universe’s time cannot be marked thusly. Such a crooked and flimsy device could only keep the fantastic hours of unruly ghosts. The front plate of the works is taken in hand and fitted first onto the upfacing arbors of the main and strike springs, these being the largest and most easily fitted of the sundry parts. This accomplished, the horologist then lifts the rickety sandwich of loose guts to eye level, holding the works approximately together by squeezing the two plates, taking care to apply neither too much pressure (thus damaging the finer of the unaligned arbor ends) nor too little (thus causing the half-re-formed machine to disassemble itself back into its various constituent parts, which often flee to dusty and obscure nooks throughout the horologist’s workshop, causing much profaning and blasphemy).

How a degree helps a technical writer

A college degree can help you in technical writing, though maybe not in the ways you expect.

How relevant is a college education for the field of technical communication? A couple of very good and influential tech writing blogs have recently discussed this issue:

• Why Tech Comm Is a Career Path of Last Resort for Students, by Tom Johnson, about an English department
• Rhetorical theory vs. tech comm reality, by Ryan Fulcher, Scriptorium, about a tech comm program

The question is both pertinent and impertinent, because Tom and Ryan frame it in a way that devalues college education [… at least in the specific program they are criticizing, see Ryan’s comment below. 18 Nov 2010]. Tom says tech comm “should not be taught in the context of an English department, because [it] is not understood or encouraged in traditional English curricula.” Ryan says he’s gained more useful knowledge in 5 months in the job than in his entire time in the tech comm MS program. I cannot argue with their experiences, and I cannot hope to convince them otherwise.

To help anyone with similar questions who’s in college now or has recently graduated, I can offer my own alternative assessment: How a college degree helped me become a passionate and, I dare say, good technical writer.

What I sought

Computer Science and Business as a combined major was how I started college. I sought to learn how to build software and how to run a business. What I got was learning by rote, too much how it’s done and not enough why and how it could be done better. I dropped the major after a semester.

I had embarked on rational and reasonable education and found that my heart wasn’t in it. I just couldn’t see myself spending several years getting a degree as a means to an end. I expected college to teach me something that was interesting in its own right, not a promise that I could apply it in a future job, or maybe not.

American Studies is what I declared as my major after two weeks of soul searching. That’s where I found my academic home. The curriculum was heavy on literature, social history and culture. The emphasis was on understanding what holds the USA and its culture together, to come to terms with its cultural and artistic developments, and to use whatever academic theories could be made useful.

Over ten years ago, I’ve received my M.A. in American Studies. I’m a technical writer by choice and practice, with the heart and the outlook of an Americanist.

What I learned

In American Studies, I learned a lot of things. Almost all of them do not directly relate to technical writing. Here are some things that I’ve found useful and applicable as a technical writer:

• How to write long, coherently argued, understandable papers in correct English. It took me a long time to get it right. It took me longer yet to realize the importance of tailoring my message and language to my audience. And it took me even longer to realize that all this combined is a rare and marketable skill.
• How to explain something that defies explanation to people who think they already know how it works. After you’ve ever tried to explain America to Germans who have it all figured out from movies and news media, writing user manuals is actually pretty easy. Most products I’ve dealt with are less complex than a country of 310 million people, even if you only regard the most recent 400 years.
• How to cope with complexity. Literary studies can appear pretty neat, especially when you deal with only one author or one book. Studying a country and its culture is a more daunting task, not least because the people carry on so, with no regard for your studies. Trying to keep your insights reconciled with an ever-changing reality is a good preparation for your survival in large corporate environments and their organisational quirks.
• How to organize to finish. Formulating a thesis and then framing and arguing it was part of my later assignments. That was a good preparation for writing user manuals from scratch. The “thesis” in that case is the easy part. The customer wants to do stuff with the product and look cool while doing it. But the rest is again up to the writer: Framing the text in a context of use, consulting all available sources, explaining it in the most understandable and most efficient way.
• A turn of phrase occasionally: That a question can be both pertinent and impertinent (see above) is something that I learned from Thoreau’s Walden, the second paragraph of the “Economy” chapter to be precise.

What I know now

A college education can work very well for you, if you take it for what it is and don’t expect something that it isn’t. Stanley Fish makes a very astute argument for what a university can be and do:

When it comes to justifying the humanities, the wrong questions are what benefits do you provide for society (I’m not denying there are some) and are you cost-effective. The right question is how do … your program of research and teaching fit into what we are supposed to be doing as a university.

It’s important to realize that this kind of education comes with no guarantee: It guarantees you neither a job, nor happiness, nor that you’ll always be right or make the right decisions.

But it gives you the tools to gather information, take responsibility and make the decisions that affect your life. In short, such an education can give you hope. In the words of Václav Havel, writer, dramatist, and the first President of the Czech Republic:

Hope … is not the conviction that something will turn out well, but the certainty that something makes sense, regardless of how it turns out.

Your turn

What did you get out of a college education? Was it useful for immediately applicable skills? Was it instrumental to become who you are? Or was it a waste of time?