Why FAQs are the Tech Writer’s Secret Weapon

Most questions have been asked before. This isn’t a profound statement; most of us would consider it obvious. Just ask anyone on your Product Support team. Chances are the majority of calls they receive are fielded with canned answers. Why? Because we all seem to ask the same questions. By providing answers to those questions, you can help the majority of your users get back on track quickly.

Haiss, Craig. DMN Communications (2009). Articles>Writing>Technical Writing>FAQ

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

Writing Technical Articles

Some advice on writing articles about technology (and other topics) for a mass audience.

Nesbitt, Scott. ScottNesbitt.net (2008). Articles>Writing>Technology>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

Moving into User Research: Establishing Design Guidelines

The best technical writers do user research to understand the audience for their documentation, create user profiles or personas, perform task analyses, and do usability testing to ensure that their documentation meets users’ needs. All of these are activities in which a user researcher engages. Thus, as a technical writer, you can start amassing experience in user research and building a portfolio of user research documentation.

Six, Janet M. UXmatters (2009). Articles>User Experience>Research>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

What Makes a Technical Writer Tick?

Technical writers are Jills and Jacks of all trades. But what really makes a tech writer tick? In this guest post, Sarah Maddox explores that question and comes up with some interesting answers.

Maddox, Sarah. DMN Communications (2009). Articles>Writing>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

This is the Future of Technical Communication

In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you've done with brackets.

O'Keefe, Sarah S. Palimpsest (2009). Articles>TC>Technical Writing>Wikis

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

Think Mobile When You Write

Always keep the small screen in mind when you’re preparing your docs. There are some W3C “mobileOK” guidelines to consider to ensure that your content meets requirements. Here are some highlights.

Norris, Julie. 2moro Docs (2009). Articles>Web Design>Wireless Web>Technical Writing

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

Realistic But Hypothetical Examples

One of the reasons that technical communicators ought to know the business processes of their users (or at least the reasons they’re using the product) is to generate effective examples in the documentation.

Minson, Benjamin. Gryphon Mountain (2009). Articles>Writing>Technical Writing>User Centered Design

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

Why Tech Writers Need To Understand Business: Yet Another Example...

For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions.

Perlin, Neil E. Blogspot (2009). Articles>Business Communication>Technical Writing

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

Cop vs. Consultant

Pay attention to the legal requirements and translatability issues, not only in your own documents, but in the documents of other groups like marketing and engineering. It's an area where we add value.

Hughes, Michael A. User Assistance (2009). Articles>Intellectual Property>Trademark>Technical Writing