How do Brain Rules affect technical authors?

Yet again, a post by Garr Reynolds has made me wonder about how his advice about presenting crosses over into the world of technical authoring.

Garr's latest post is about Dr. John Medina's book "Brain Rules", which has 12 principles for surviving and thriving at work, home and school. He's also created a slideshow about the book:

| View | Upload your own

Here are my initial thoughts on how some of the rules affect technical authors:

ATTENTION | Rule #4: We don't pay attention to boring things

Medina states multi-tasking is myth. We need to dedicate our attention to one thing at a time. In this situation, a paper manual scores, as we can read it in a peaceful and distraction free envionment. That's a lot harder to do with on-screen information, with email notifications and other "noise" vying for our attention.

SHORT-TERM MEMORY | Rule #5: Repeat to remember.

Do we expect users of user manuals, and Help files in particular, to remember what is contained within them? Are they there simply to be followed and then forgotten?

VISION | Rule #10: Vision trumps all other senses.

Technical manuals probably don't contain enough images. This may be because they are hard to maintain, authors are wordsmiths rather than graphics designers, and they take time to do. Writers of Help files avoid using screenshots to avoid users confusing the Help file with the application itself. However, given the effectiveness of visuals, perhaps they should include more?

What do you think?

The $110K Technical Communicator

We've currently got a vacancy on our books offering the highest salary we've seen for a senior technical author: £50K-£54K plus benefits, pension contribution etc. That's roughly $110,000 per annum, with no healthcare fees or "co-pays" to come out of that. The catch? You need to be based (or legally entitled to work) in the UK , and have the skills and experience they're looking for.

What does single sourced content mean to readers?

Lyn Gattis kindly sent us a copy of her PhD dissertation over the Christmas break. She used some content from the Cherryleaf Web site in her dissertation, which looked into the comprehensibility of single sourced technical documents.

In her dissertation, Lyn painted this scene:

"Judi Greene is evaluating the capabilities of 'CommonText', a new single sourcing application. She recognizes single sourcing's potential for greater efficiency in a rapidly changing publishing environment, but questions whether single sourcing truly serves readers well."

This imaginary Documentation Manager's concerns are:

• How well can single sourcing methods accommodate rhetorical variations that would improve reader comprehension?


• Is highly standardized text appropriate for cross-cultural audiences?


• Does removing meta language, particularly cohesive devices, from single sourced texts significantly affect comprehension for specific groups of readers?

The key result from Dr. Gattis's study indicates that readers are more likely to comprehend texts with lexical repetition (which are often sacrificed in single sourced documents and online Help files). When texts are cohesive, readers are more likely to consider information to be clear, well organized and easy to follow.

Dr. Gattis's conclusions coincide with future trends we and others have hypothesized:

• Human editorial oversight will continue to be essential for comprehensibility, even when composing is partially automated.


• Technical Communicators may need to specialize on different tasks within the team.

In addition, she argues:

• Documentation teams will need to resist system efficiency as an overarching goal.


• Lexical repetition, cohesive devices and other textual features will need to be incorporated into specifications right from the start, i.e. during the document planning stage.


• Organizations have several options for integrating cohesive devices into single sourced texts. However, these options may reduce writer productivity.

One solution is to build cohesion into templates, boilerplate documents, style sheets, DTDs and/or schema.

Interestingly, this was the approach by RePublico software (now defunct), and are capabilities being introduced into AuthorIT and similar tools.

The secrets of effective technical authors

In early 2007, Cherryleaf carried out a survey to find out the challenges technical authors face. We looked at satisfaction levels, the status of authors and what was holding them back, if anything. We also looked at other research on what makes a good writer. We received nearly 500 responses, and we presented our conclusions at the Online Help Conference Europe 2007.

Our objective was to identify areas where there might be opportunities for new training courses and consider publishing a report on what makes a successful technical author.

In general, we found that authors were confident in their own capabilities and the quality of the work they delivered. However, when we asked “What is holding you back?” some fascinating themes came out.

We categorised these as:

(1) office politics (in other words, “nobody loves us”)
(2) project management and
(3) time management.

A key theme coming out from the responses boiled down to authors complaining that their work colleagues didn’t know their value.

When we mentioned our findings to Anne-Florence Dujardin, one of the tutors in Technical Communication at Sheffield Hallam University, she pointed us towards some research carried out by one of her former students in 2002.

This student, Deborah Shapiro, had looked at the personality traits of success in technical authors. In her preliminary study of 223 software technical authors, she had found that effective technical authors had high “openness” and “agreeableness” (defined as “trust of others” and “likeability”), when their personality was measured on the OCEAN personality and PEI effectiveness profiling systems. One of her conclusions was that technical authors should negotiate more, and be more assertive, while maintaining good work relationships. In her words, “skills, language and technical knowledge are sometimes not enough to be an effective technical writer”.

Shapiro’s findings concurred in many ways with our own experiences. It seemed that the solution to being a successful technical author lay not only in being a good writer, but also in being good at positioning, promotion and project management.