“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

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

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

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

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

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

Dividing It Up, With Any Crowd

When you think of the crowd, you probably think about a specific mass of people who use the software and hardware that we document every day. The interesting thing about the crowd is that it doesn’t necessarily mean people outside of the enterprise in which you’re working. There are people in your enterprise who can do a lot to help you with the documentation, too. Developer, product managers, QA analysts. They all have knowledge that you can and should tap.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Social Networking>Technical Writing

Is Help Necessary?

Do we need to have an external help system? Why not embed help right into the application? Why not take this a step or two further? Instead of having a separate help system, integrate more useful, more robust, and context-sensitive help into the user interface.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Help>Technical Writing

Form and Function

A musing on the need to balance documenation that looks good with documentation that has substance.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Document Design>Technical Writing

Finding Information in Documentation

Finding information in documentation is easy. Or is it? This blog post argues that there's no universal solution, and that each document and each delivery method offers challenges and requires a slightly different solution.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Usability>Technical Writing

Identity and Authority. Why the Foundation of Documentation is Changing

There is most definitely a technical communicator identity crisis underway. Three posts from well respected industry professionals in the span of one month, all dealing with a fundamental shift in an core product development profession. What’s going on here? To put it plainly: documentation now has competition.

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

Twitter as a Medium for Release Notes

I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes.

Maddox, Sarah. ffeathers (2009). Articles>Documentation>Social Networking>Technical Writing

Reveal Bugs in Release Notes, Not User Guides

Really, I think documenting the software the way it works with bugs is making more work for myself, so that’s probably the main reason I avoid it. I’ve got enough to do without changing the doucmentation whenever a bug is fixed. Release notes are easier—a much smaller deliverable whose focus is what’s changed and what’s still not quite right.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Documentation>Technical Writing

Writing User Manuals

Writing user manuals isn't so difficult if you start with a clear understanding of the structure of such documents. This post will provide you with some guidelines for producing a great manual, and links to templates to help you get started.

HelpScribe (2009). Articles>Documentation>Technical Writing>Writing

Documentation for Consumer Products: Give it a Chance

Documentation for consumer products gets a bad rap. Often, it's deserved. But you can't paint all documentation with the same brush. This post looks at the good and the bad in consumer documentation, and at the elements which can make that documentation good.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Technical Writing

Authoring Tools Do Matter

The authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.

O'Keefe, Sarah S. Palimpsest (2009). Articles>Documentation>Technical Writing>Software

A Mile Wide and 30 Seconds Deep: A Metaphor for Help from Mike Hughes

Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point.

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

Writing Technically: Bad Docs Rarely Mean Bad Sales

Technical writing is a cost activity, not a revenue or a profit activity.

Basu, Anindita. Writing Technically (2009). Articles>Documentation>Technical Writing>Technology

Let's Reinvent Technical Writing

More and more, I think it’s time to discard main approaches to tech writing and come up with new methodologies. The world and technology is changing so much that I think it’s time to start fresh. Just as sometimes when you’re working on a sentence and you tweak it and change it, but it’s still not quite right, and you finally just drop it and come up with something different. Perhaps it’s time to drop existing methodologies and develop something new instead of trying to tweak what’s there to fit what’s happening now. Perhaps the old methods no longer work.

2moro Docs (2009). Articles>Writing>Technical Writing>Documentation

What’s the Point of User Documentation, from a Marketing Perspective?

In order to understand the way marketing people see the world, it’s worth reading Blogs on marketing (by people such as Seth Godin), the Cluetrain Manifesto, and reading a few books on marketing.

Pratt, Ellis. Cherryleaf (2009). Articles>Documentation>Technical Writing>Marketing

Cut, Cut, Cut your Content and Procedures

Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium.

2moro Docs (2009). Articles>Documentation>Technical Writing>Minimalism

How to Capture the Essence of a Topic

Capturing the essence of a topic is the heart and soul of good writing and editing. If you cannot tell what the main idea is, you cannot write it either. And if you cannot write it, how would you expect your readers to get it? So it all starts with you. Thankfully, it is not mysterious process. Here are two techniques that you can use to weed out the irrelevant details from your core idea.

Technical Communication Center (2009). Articles>Documentation>Technical Writing