I'd Rather Be Writing » books

40 Foundational Books for Technical Writing

Tom Johnson — Fri, 10 Sep 2010 14:35:47 +0000

I received the following question from a reader:

I have semi-transitioned to a new position at my job where I’m responsible for creating and maintaining documentation for our systems, programs, policies, etc. I was selected for the position because I have written many tutorials for our applications to be read by new employees. Since I have no formal education in writing (I love to write, but I majored in accounting with a masters in information technology), I’d like to learn the basics of it. Can you recommend any books (I live in the US) which provide a decent foundation into the field of technical writing?

I asked my Twitter and blog friends to respond with their recommendations. Here they are (the name in brackets after the book is the person who recommended it):

Technical Writing, by T.A. Rickard, is a seminal work. You can find it in many academic libraries. You’ll be amazed by how the emphasis on fundamental writing skills hasn’t changed. [Mike Frasciello]

Managing Your Documentation Projects, by JoAnn T. Hackos, while 15 years old, still applies today for most areas of project management for technical communication projects. [Dave Brock]

Technical Writing 101: A Real World Guide to Planning and Writing Technical Documentation, by Alan Pringle and Sarah O’Keefe, is a good starting point. [Tom Johnson]

Technical Communication, 9th edition, by Mike Markel. I’ve taught several Effective Technical Communication classes for non techcomm majors such as engineering students, IT students, etc. using this book and the online resources. Most of them keep the book in their jobs as a reference on how to write for various situations. [Ben Woelk]

Managing Writers: A Real World Guide to Managing Technical Documentation, by Richard L. Hamilton. This provides a good overview for managers who are suddenly called to manage technical writers (and who have no idea what they do). [Tom Johnson]

Trees, Maps, and Theorems, by Jean Luc Doumont, is good for engineering students who have to write reports and other scientific papers. [Tom Johnson]

This isn’t a book, but listening to the backlog of podcasts on Idratherbewriting.com will give you a good foundation into the field. See http://idratherbewriting.com/podcastslist. There’s also a special collection of posts for students or other professionals transitioning into the field of technical writing: http://idratherbewriting.com/for-students. [Tom Johnson]

You could also listen to the latest STC sessions by buying the Summit @ a Click, which has about 90 recorded sessions on tech writing related topics. [Tom Johnson]

Technical Writing Wikiversity also provides a lot of good information online for free. [Tom Johnson]

Conversation and Community: The Social Web for Documentation, by Anne Gentle, provides a good approach to integrating technical writing with social media. [Tom Johnson]

On Writing Well by William Zinsser, a classic on non-fiction writing.

Elements of Style by William Strunk Jr. et. al., another classic for writing.

It might help to keep a few reference books on the shelf. Here are a few of my favorites: [Quinn Warnick]

Two classics on writing and revising: Writing with Style, by John R. Trimble, and Revising Prose, by Richard A. Lanham (Lanham’s Revising Business Prose is good, too, though it’s in desperate need of an update.) [Quinn Warnick]

If your reader isn’t opposed to buying a “textbook,” The Essentials of Technical Communication is pretty good. I’m using it in my tech comm class for the first time this semester and, so far, I’ve been impressed with it. It’s concise, practical, and surprisingly honest about the challenges and pitfalls of writing in technical and corporate environments. [Quinn Warnick]

Writing Tools by Roy Peter Clark — Written for Journalists, but is a great collection of articles on writing well and using good rhetoric.

Developing Quality Technical Information, an easy to read manual with plenty of example, written by technical writing professional and editors at IBM. [Seth Packham]

Audience, Relevance and Search: Targeting Web Audiences with Relevant Content, by James Matthewson and others, provides an excellent primer on writing for the web, keeping in mind SEO and other concepts. [Tom Johnson]

Cognitve Surplus, by Clay Shirky, explains why users want to contribute (and why sometimes they don’t)

Technical writing : a reference for technical writers at all levels, by Diane Martinez, published by Kaplan Pub. (2008). A new version (updated) is coming out at the end of 2010. I like this book; it has good information for new writers and for writers who have been in the ‘biz for awhile. [Adriana Harper]

Handbook of Technical Writing (9th Ed.), by Gerald J. Alred, Charles T. Brusaw, Walter E.Oliu. This is a reference book and I find it works nicely side by side with something like The Elements of Style (Strunk and White). [Adriana Harper]

Technical Writing for Dummies, by Sheryl Lindsell-Roberts. This focuses on the basics. Great for getting an insight into Technical Writing. [Anne-Marie Lansley]

Rapid Instructional Design, 2nd edition, by George M. Piskurich. This is great if you’re new to instructional design and e-learning. [Anne-Marie Lansley]

Practical DITA: an XML based architecture for authoring, producing, and delivering technical information, by Julio Vasquez. [Tom Johnson]

DITA 101: Fundamentals for Authors and Managers, by Ann Rockley et al [Tom Johnson]

Read Me First! A Style Guide for the Computer Industry

Style: Toward Clarity and Grace, by Joseph M Williams. The best book on the craft of writing that I’ve come across. All writing, all communication, can be improved by mastering a technique or two. But tech writing requires mastery of every single one of them. How come? Because your reader isn’t in a good mood when they’re reading your stuff. [Sharon Twiss]

Microsoft Manual of Style for Technical Publications. If you’re to document a UI or tell a user how to do something, this guide is invaluable. It encompasses the standard phraseology and “dogma” of telling a user how to do something. It has been the same shtick since 3.1.1, but it has set the standard of a users expectation. I too like the dummies/idiots books to get back to the basics. From reading your blog for almost a year, I think you have the technical side covered. [Mike Walsh]

The Elements of Technical Writing, by Gary Blake and Robert W. Bly [Mark Brennan]

Designing and Writing Online Documentation, by William Horton

Technical Writing: Process and Product (5th Edition), by Sharon J. Gerson and Steven M. Gerson. This book guides technical writers through the entire writing process — prewriting, writing, and rewriting.

Technical Writing Basics: A Guide to Style and Form (3rd Edition), by Brian R. Holloway. This book includes direct practical explanations, real-world examples, and a variety of “role-playing” exercises. [Rachana Khatri]

Is the Help helpful? by Jean Hollis Weber. Lots of checklists, lots of good advice for writing online documentation. [Rhonda Bracey]

Don’t make me think! by Steve Krug. Essential reading for anyone involved in any sort of design — web design, GUI design, product design, etc. [Rhonda Bracey]

Grammar, Punctuation, and Capitalization: A Handbook for Technical Writers and Editors, by Mary K. McCaskill (Langley Research Center) is a NASA guide for documentation. Though not strictly for software industry, this comprehensive manual provides extensive and detailed specifications for good technical writing. [Gautam Soman]

Online Technical Writing Textbook, by David A. McMurrey. This textbook is freely accessible to anyone who needs help with writing for business, science, and technology. [Rachana Khatri]

JoAnn Hackos’ book mentioned near the top of the list is top-notch but heavy duty stuff. Don’t read it first if you’re just starting out.
Also not a book, and a tad disorganized (it’s a blog, after all), but with engaging posts on a variety of topics relating to writing clearly: http://writing-rag.com. [Rogers George]

Blog Sponsors

Upcoming Books from XML Press: Richard Hamilton at the STC Summit in Dallas, #stc10

Tom Johnson — Fri, 07 May 2010 13:47:02 +0000

In this video, I talk with Richard Hamilton, founder of XML Press, an imprint focused on technical communication, to share details about the upcoming books he is publishing. Richard also comments on how he identifies topics and trends for the technical communication publishing market.

Blog Sponsors

The Long Tail Applied to Writing

Tom Johnson — Tue, 20 Apr 2010 14:14:21 +0000

As I implemented the Organize Series plugin for my long essay about moving From Overlooked to Center Stage, an interesting idea dawned on me: The Long Tail applies to writing as well.

The Long Tail is an economic principle claiming that an abundance of little sales of niche products eventually outproduce the mega sales of mainstream products. For example, Amazon.com may not sell many 1970 Grateful Dead glass mugs, but if it sells 10,000 niche products like this for less than $10, over time the sales of those niche products will outperform the sales of the mainstream products (such as CDs of Brittney Spears).

Analysts apply The Long Tail to just about anything. I haven’t seen it applied to writing yet, but here’s an application. Sitting down to write a book is hard. It’s so daunting that few even attempt to do it, despite the intentions so many of us have.

But instead of trying to write an entire book, writers would be more strategic to write a series of small posts. Over time, these small posts will accumulate into a book-length size. For example, I have more than 1,000 posts on my site. I probably have about a books’ worth of material. I don’t have the time to sit down and write a real book, but apparently if I had approached the book like a series of blog posts, I could have already written one.

The problem is that blog posts are so random, they often don’t string together into a longer work. But if I were to approach the posts by subject, linking them together in a series like I did last weekend, the results might be more worthwhile. You might really be able to string them together into a longer work.

Given this model, I may be experimenting more with series posts, diving into a topic for a while, linking the posts together, and then perhaps sitting down on a weekend to cull and refine and reorganize the series into a single essay that flows from start to finish. (My personal reading preference is for essays rather than books anyway.)

Not only is this idea more practical, it also harnesses the blog platform for something that has more depth.

Blog Sponsors

How to Incorporate Twitter into Your Presentation

Tom Johnson — Sun, 15 Nov 2009 07:16:34 +0000

At the Intermountain STC workshop this morning, we talked about how to build an online presence. During my portion of the workshop, I facilitated a discussion using Twitter. With the dozen participants, all sitting in front of computers with Internet access, I told them to go to Search.Twitter.com and search for the #imstc hashtag.

I posed a question for them to answer via Twitter. They responded, including the #imstc hashtag. When you include a hashtag in your tweet (placing it anywhere), you can read an aggregated view of all tweets tagged with that hashtag at search.twitter.com. After everyone responded, we read through the responses out loud and discussed them a bit.

The question I posed on Twitter

When the discussion ended, I posed a new question for them to answer on Twitter and gave them a few minutes to respond. Then we read through the answers one by one, looked at trends and discussed them for a while. We did this about 4-5 times over the course of an hour. You can read the thread here.

The technique worked well because it required everyone to stay engaged. During most presentations, you can sit back and turn on your passive listening mode. But if you’re periodically interacting on Twitter to respond or analyze a question, it keeps you awake. And as a presenter, it’s a lot more fun when everyone is engaged like this.

I’m growing tired of presentations that are little more than lectures, so I’m going to experiment with more user-led techniques like this. Unfortunately, available wi fi at chapter meetings or conferences with participants who have computers or mobile data devices is pretty rare. But if you do have the opportunity, definitely try incorporating Twitter, even if only for Q&A at the end of your presentation.

Blog Sponsors

How the Web and the Weblog have changed Writing

Tom Johnson — Mon, 06 Jul 2009 03:32:33 +0000

How the Web and the Weblog have changed Writing. I saw this on Gordon Meyer’s blog. It talks about how blogs and web publishing have provided venues for texts that, due to incorrect page length, wouldn’t have otherwise been published. Traditionally, texts had to be either 5 pages for magazines or 200 pages for books. Blogs now allow paragraph-length thoughts or 20 pages essays. Length (either too long or too short) is no longer a deterrent to publishing.

Blog Sponsors

Great Books by Writers Who Aren't Dead Yet

Tom Johnson — Wed, 21 Jan 2009 14:37:46 +0000

Great Books by Writers Who Aren’t Dead Yet

My friend Josh just started this site. He’s an English professor at BYU Idaho. It’s an online book club involving discussion of excellent literary authors still alive.

Blog Sponsors

Goodreads | get book recommendations from people you know

Tom Johnson — Sat, 06 Dec 2008 04:47:11 +0000

Goodreads | get book recommendations from people you know.

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Tom Johnson — Tue, 23 Sep 2008 04:36:09 +0000

Everyone knows it’s a good practice to chunk your help material into discrete topics, but how granular should you chunk it?

Take a look at this Microsoft Word 2007 help topic on inserting headers and footers.

Example of a Quick Menu from Microsoft Word's Help on inserting headers and footers

Although inserting headers and footers is the main task, the topic really has 11 related tasks:

Insert the same header or footer on each page
Make the first page header or footer different from the rest of the pages
Use no header or footer on the first page
Make the header or footer different for odd and even pages
Make the header or footer different in each section or chapter
Change the contents of a header or footer
Insert a page number
Insert the file name of the document
Insert the document title, author’s name, or other document property
Insert the current date
Remove the header or footer

The author could have created 11 separate topics. Do you agree with Microsoft’s decision to group all of these subtasks into the same topic? Or would you rather explore each subtask as a separate topic in a table of contents?

Although the practice of single sourcing encourages chunking of tasks, if you won’t be reusing the subtasks or related tasks independently, there’s little reason to separate them out into discrete topics. Forcing all of these subtasks into separate topics would severely bloat the table of contents (TOC), rendering it not only less usable, but also more intimidating. Your application’s apparent complexity would magnify.

Separating each subtask into its own topic often forces users to click in a non-linear pattern from topic to topic as they search for the right task. This nonlinear clicking can give users a headache. It’s part of the reason why reading online is more strenuous than reading a book. Books provide more of a hierarchical layout and logical progression of ideas. In contrast, the web is a scattered maize.

Consolidating subtasks into one topic also improves the user’s ability to find topics. With fewer topics in the TOC, the user can actually browse the TOC and find the right topic. But even if the user reverts to keyword searches, the longer topics will have greater keyword density and more likely rise to the top in search results.

I sent a question across Twitter the other day asking whether anyone had done research into this issue, and Brenda Huettner pointed me to a Web Usability Guidelines reference book. Chapter 8 echoes Brenda’s response that “it depends.” The authors say that older people are slower at scrolling, but comprehension may be better because the user remains on the same page. Here’s an excerpt:

Guideline: Use longer, scrolling pages when users are reading for comprehension.

Comments: Make the trade-off between paging and scrolling by taking into consideration that retrieving new linked pages introduces a delay that can interrupt users’ thought processes. Scrolling allows readers to advance in the text without losing the context of the message as may occur when they are required to follow links.

However, with pages that have fast loading times, there is no reliable difference between scrolling and paging when people are reading for comprehension. For example, one study showed that paging participants construct better mental representations of the text as a whole, and are better at remembering the main ideas and later locating relevant information on a page. In one study, paging was preferred by inexperienced users.

Sources: Byrne, et al., 1999; Campbell and Maglio, 1999; Piolat, Roussey and Thunin, 1998; Schwarz, Beldie and Pastoor, 1983; Spool, et al., 1997; Spyridakis, 2000.

In other words, each time a page loads, you interrupt the user’s thought process. By remaining on the same page, the user can better grasp the concept as a whole.

Thanks for the resource, Brenda! In the studies, the content consisted of web pages rather than help material. Some of the examples for scrolling depict long, sophisticated pages — quite a bit more hairy than the Word example above. Still, I agree with the general findings and think they apply to help authoring.

My colleague Ben Minson, however, raises an important objection to long topics. He says,

In reality, people don’t want long topics. They want to think that procedures are short and simple. Long topics intimidate people and make them reluctant to consult the documentation in the future. (“Long Topics: A Help Author’s Crime Against Humanity“)

I agree that no one wants to be confronted with a massive topic when all they need is information to complete simple task. However, adding a quick topic menu at the top, similar to the following image, seems to solve that problem, doesn’t it? The user can jump immediately to the relevant topic, rather than meticulously scrolling down and checking each heading.

[image title="Example of a Quick Menu" size="full" id="2017" align="left" linkto="viewer" ]

Overall, in my experience, it’s easy for a help’s TOC to grow successively larger as you think of more and more scenarios, possible tasks, and concepts to explain. But if you reach the end of the project and see that your initial 50 topics have grown to 250, I think something’s wrong. Most applications aren’t that complicated. When users expand the TOC and find a seemingly infinite number of topics, it’s the equivalent of the disheartening “thud” from a long printed manual.