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

Textual Grounding: How People Turn Texts into Tools  

The author argues that users see texts as tools when they recognize the texts' specific value and function within highly localized use settings. The author argues that users "ground" their texts to local use settings by altering the ways in which the texts structure and represent information (e.g., underlining, annotation, and sketching). The author discusses three practices by which texts are grounded as tools in document reviews: mode shifting, layering, and marking. These practices reflect different ways by which users add, subtract, and restructure information in a text so that it is usable under very specific conditions. This article explores document review as a practice in which grounding is the object of discussion (how others use the reviewed documents) and a practice by which review is facilitated. These observations will be important for exploration of technology to support "grounding" practices.

Swarts, Jason. Journal of Technical Writing and Communication (2004). Articles>Documentation>Writing>Theory

Change is Gonna Come

There's a shift happening in the way in which documentation is produced. We’ve all seen the beginning of it: the growing volume of what’s called (among other things) user generated or crowdsourced documentation. That trend is growing. And while a number of people in our profession are still resistant to the idea, it’s only a matter of time before users are our main partners in creating documentation.

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

Why Technical Writers Shouldn't Be "Writers"

Technical writers love the written word. Perhaps, we love it a little too much? We need to ask ourselves is the written word the best thing for documentation? Is it the best thing for us as an industry, and is it the best thing for you as a content developer.

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

Sometimes, Simple is the Way to Go

I’m advocating boiling the documentation down to the essentials. Remove any superfluous material. Tell the user how to do things with a piece of software or a gadget, not what that something can do. You might wind up with documentation that’s just a set of procedures connected together by linking material and cross references. Don’t bog them down with what’s not necessary for them to get things done in a fast and efficient way.

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

The Missing Manual Authors’ Guide  

This Authors’ Guide tells you everything you need to know to write Missing Manual. It starts out by giving you a brief introduction to the Missing Manual way of explaining things and then takes you through the nitty gritty of style guidelines, figure formatting, and so on.

Missing Manuals (2009). Articles>Documentation>Style Guides>Technical Writing

Seven Steps to Clear Technical Writing

These points are not meant to be all-inclusive. However, if you are new to tech writing, this should put you on the right road.

Walsh, Ivan. I Heart Tech Docs (2009). Articles>Writing>Technical Writing>Documentation

Change Your Writing Style to Make Documentation More Usable and User-Friendly

When the subjects of usability and user friendliness in relation to documentation are broached, writing isn’t often the first thing that comes to mind. But it should be.

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

Technical Communications as a Profit Center

Those within technical communications have long argued that product documentation provides significant value in terms of a customer satisfaction and downstream savings in customer support and service. In the broader, enterprise perspective, however, documentation is generally viewed as simply one of many requirements for product launch. This perspective is often the result of the lack of visibility that is generally available into the business value contributed by product documentation. Aberdeen investigated and isolated the quantifiable business impact of technical communications makes for 165 participating companies. An analysis of this data indicates that when leveraged effectively, technical communications stands to contribute as much as a 42% increase in customer satisfaction and an associated 45% increase in product revenue. This report provides a quantified framework for understanding the potential impact on technical communications makes for business profitability as well as the best practices to adopt to drive greater value from this organization.

David Houlihan. Aberdeen Group (2009). Articles>Documentation>Workplace>Technical Writing

The Doc Whisperer

Doc whisperers are more commonly known as "senior technical writers", but what's in a name anyway? So if you want to be a great tech writer—start whispering.

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