Quick Reference Guides: Short and Sweet Documentation

In this article, my colleague and I provide strategies, tips, and approaches we’ve learned in creating quick reference guides for software documentation projects.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Quick Reference

Twitter and Tech Communication

Twitter can be a great tool, and can help people get answers quickly. However, when you have a question and need an answer, you probably ought to consider your question, and determine what channel is best suited for the type of answer you need. That may or may not be Twitter.

Pehrson, Paul. Technically Speaking (2009). Articles>TC>Technical Writing>Social Networking

The Case for Simple Numbering

Rather than spend hours coming up with a complex numbering scheme, this might be an excuse to implement something far more straightforward discovered by an extensive readability study at IBM, of which I was a part. My work involved sitting behind a one-way mirror with a stopwatch, watching people take tests that involved, among other things, "how fast can you find Figure 3-4?" We had cameras mounted over the participant's shoulders and could watch them thumb through the documents, and we also monitored eye movements. Then we followed up with a short interview where we got feedback.

Techknowledgecorp (2007). Articles>Document Design>Information Design>Technical Writing

What Should You Include in Your User Documentation?

Technical authors are faced with limited time and resources, so they often are faced with the dilemma as to what to include and what to leave out of their user documentation. You may ask, if 80% read only 20% of the content, is there any value in documenting the rest?

Cherryleaf (2009). Articles>Documentation>Technical Writing

The Matter of Dark Text

Dark text refers to the many layers of hidden meaning in any text segment. It ranges from the implied meaning that the author intended, or that the reader infers, to much deeper, more hidden meanings. As technical writers, we must be aware of dark text, and where possible, try to minimize it.

Tech Writer's World, A (2009). Articles>Documentation>Technical Writing

Technical Writing: What is It?

Technical writing is the presentation of information that helps the reader solve a particular problem. Technical communicators write, design, and/or edit proposals, manuals, web pages, lab reports, newsletters, and many other kinds of professional documents.

Jerz, Dennis G. Seton Hill (2000). Articles>Writing>Technical Writing

What if Readers Can't Read?

If we really do believe in the importance of the audience, the reader, the user, then how have we changed our practice to reflect the changing characteristics, competencies and even literacies of our readers? Have our readers changed over the past few years? The evidence points to the answer being a resounding yes!

Self, Tony. HyperWrite (2007). Articles>Writing>Technical Writing>User Centered Design

“Good Enough” Really Isn’t

I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent.

Gryphon Mountain (2009). Articles>Documentation>Quality>Technical Writing

Two Stories About How to Write Help

The mindset in which most technical communicators write help is sometimes fundamentally flawed. Consider the following two stories and the different approaches and mindsets each writer takes toward the project.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Technical Writing>Help

User Paradox with Not Reading User Manuals

Users would save time by reading the manual, but instead they try to figure the application out themselves and then get lost/frustrated as they end up spending even more time getting up to speed with the application.

Johnson, Tom H. I'd Rather Be Writing (2007). Articles>Documentation>User Centered Design>Technical Writing

Quick Reference Guides: Short and Sweet Technical Documentation  

Users often want documentation in a format that will give them the basics and get them on their way as fast as possible. Quick reference guides provide a short version of a manual, condensed from dozens or hundreds of pages down to just one double-sided sheet of paper. Despite the brevity of quick reference material, the thought process involved in creating, organizing, and laying out the content is time consuming. The format requires you to assess the content and decide the most important information the user needs to know. You must describe with extreme concision and clarity processes that usually require dozens of pages to explain. This article provides an overview of the strategies, tips, challenges, and benefits we have learned in using quick reference guides for our documentation projects.

Johnson, Tom H. and Benjamin Minson. Gryphon Mountain (2009). Articles>Documentation>Technical Writing>Quick Reference

What Technical Communicators Can Learn from Comics    

Citing the rise of graphic novels, comics, and in particular, Google’s new web browser Chrome, which has a comic-book-style manual, Opsteegh argues that technical communicators can learn a thing or two about conveying information from graphic novelists.

Opsteegh, Michael. Intercom (2009). Articles>Information Design>Technical Writing>Documentation

Reinventing the (Professional Writing) Major

I have been dwelling for some time with ideas for rethinking the professional writing major in response to phenomena that aren’t going away, such as the inadequacy of the university for life-long learning and the unsustainable way that public education is funded.

Grabill, Jeffrey T. WIDE Research Center (2009). Articles>Education>Technical Writing>Blogs

Writing For the Market

If you’re a generalist, as most tech writers are, you write about many things in a variety of media with a number of objectives. Each new job involves determining who your audience is, what their needs are, and how your product or service can satisfy those needs. Then you need to recognize, understand, and adjust your writing so one time it appeals to the camper and the next time to the business owner.

Moore, W. Leonard. Technical Communication Center (2009). Articles>Business Communication>Technical Writing

The Many Faces of Content Management: A Primer

None of the technologies mentioned so far support the production of content for purposes of producing technical documentation. Such a system is a specific type of content management that has specialized functions for technical communicators doing multi-channel publishing, yet it hasn't spun off its own specific acronym.

Bailie, Rahel Anne. STC San Diego (2006). Articles>Content Management>Documentation>Technical Writing

Why You Need to Understand Your Readers Before You Start Writing

Knowing your document’s intended reading audience before you begin writing will always help you write more effective documentation. There are three simple questions you should always ask before you start writing.

Yee, Samantha. Technical Communication Center (2009). Articles>Writing>Audience Analysis>Technical Writing

How to Improve the UI--Really!

A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience.

Hughes, Michael A. User Assistance (2009). Articles>User Interface>Documentation>Technical Writing

Collaborative Authoring and Technical Writing

Writing is a complex, cyclical task. The writing task requires more than formulating text to express ideas, it involves data gathering, managing constraints, formulating intentions, planning, and revising goals. Much of the complexity is due to the management of simultaneous activities and constraints. Management of these processes can lead to 'cognitive overload', which in turn can negatively affect the quality of the text produced. With technical writing, these same issues of task complexity are applicable.

Spring, Michael. University of Pittsburgh (1997). Articles>Writing>Technical Writing>Collaboration

Creating Topics: Where do you Draw the Line?

It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Information Design>Technical Writing

Docs Aren't Code

In the world of development, the need to track bug reports and enhancement requests are a given. But they're not generally required for documentation, in the way they are for code Quite the reverse. For documentation, bug reports and enhancement requests provide little benefit, and generally impede progress. This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Programming>Technical Writing

Technical Writing Resources

Want to learn more about tech writing and about the work tech writers do? Below are some links of general interest that will point you in useful directions. I believe that anyone new to the field should browse them all.

Klein, William D. University of Missouri-St. Louis (1998). Articles>Writing>Technical Writing

Old Media, Technical Writers, and the Evolution of Documentation

Technical writers are an important and underutilized asset to most businesses; however, I also believe that technical writers have to fundamentally alter the way they approach the problem of educating users and helping them find the answers they need before they will be properly valued by the businesses that employ them.

LugIron Software Blog (2009). Articles>Writing>Technical Writing>Workplace

From Technical Writer to User Engagement Specialist?

Products and tools must evolve to ensure that user experience does not suffer as technical writers evolve their delivery to suit this modern age. If a user has a question, there should be only one place to search, and those results should contain relevant hits from all possible content sources.

LugIron Software Blog (2009). Articles>Writing>Technical Writing>User Experience

Growing Happy Users -- One Customer at a Time

Technical writing is a profession in transition. The way companies think of, use, and manage the people who help users make sense of and use products is absolutely changing. A lot of companies have started to use the term “information developer” to describe their technical writing positions. I don’t really care what label the profession chooses for itself, but I do know this: if technical writers don’t transition more than their job title then they will be missing out on a huge opportunity to move from the “gotta do it” category into the “can’t live without it” one.

Stern, Paula. LugIron Software Blog (2009). Articles>User Centered Design>User Experience>Technical Writing

Does Your Documentation Suck?

I’ve been browsing a lot of online documentation lately and in a past life I spent an enormous amount of time worrying about how my users were interacting with documentation. It never ceases to amaze me how bad most product documentation is, especially when the documentation is published in a half-measured attempt on the web. Do companies not realize the negative effect poor documentation, both content and presentation, have on their users?

LugIron Software Blog (2009). Articles>Documentation>Technical Writing>User Experience