Skip to main content

Tag: technical writing


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.

Read More

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.)

Read More

Error message melodrama

The Shanghai Tech Writer blog has posted a screen capture of a rather ominous error message in FrameMaker:

The licensing subsystem has failed catastrophically. You must reinstall or call customer support.

I have never been the unfortunate recipient of that particular message in the many years I’ve worked with FrameMaker. If I did encounter that message, I would fully expect it to be accompanied by the shrieking strings from the Psycho shower scene. The use of “catastrophically” is a bit over the top. The fact I need to reinstall or contact customer support sets the tone enough, thank you very much–no soundtrack or scary adverb required.

The editor in me wants “catastrophically” removed from that message. If that bit of text came across my desk for review, I would have pushed back hard on the use of that word. It’s bad enough the user has to get a solution to the error, and referring to the problem as “catastrophic” is certainly not doing the user any favors.

Read More

A different take on Twittering and technical writers

by Sheila Loring

Technical writers abound on Twitter as do blog posts on how Twitter can make you a better tech writer.

I’d Rather Be Writing has an alternate take in the article Following the NBA Can Make You a Better Writer. Tom Johnson uses the analogy of Kobe Bryant and Lebron James playing their respective positions on the court. He argues that unless you’re a one-person shop, you’re doing yourself a disservice by trying to be a Jack- or Jill-of-all-trades. Play up your strengths, and minimize your weaknesses, tech writers. Read Tom’s article for more.

Read More

Technical writing and social networks

There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:

The young’uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple’s documentation, while her son found it on YouTube.

My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple’s web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.

The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don’t think there are cut-and-dried answers here; for example, it’s unwise to make the assumption that all folk over a certain age are unaware of or don’t use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.

Read More

We’ve been localised

Over the years, I have worked on manuals that were translated, and I have helped clients with their localization processes. Despite those experiences, I’ve never been part of a project in which US English was localized (well, localised) into UK English–until now.

Cherryleaf has adapted material from our Technical Writing 101 book in its new Basics of Technical Authoring self-paced course. Cherryleaf is based in the UK, so the course is tailored for those accustomed to British English, but the content is helpful to any English speaker who wants to learn the basics of technical writing. Cherryleaf has also included exercises so students can get some experience applying the techniques explained in the course content.

(Full disclosure: Scriptorium is compensated for sales of Cherryleaf’s course.)

Read More

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.

Read More

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.

Read More