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

Sometimes, You’ve Got to Break the Rules

In a case like this, you don’t need documentation made up of perfectly-chosen words and phrases. Instead, you need something that can be easily scanned, easily understood, and easily digested. Documentation that distills the main points quickly. Far more quickly than even the kind of minimalist documentation that I encourage can.

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

Minimizing Documentation

Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation.

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

How Poor In-House User Documents Cost You Twice

Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization. If this documentation is not created or is poorly written, it costs you twice.

Millman, Barry. Technical Writer Blog, The (2009). Articles>Documentation>Technical Writing>Business Case

Coffee and Documentation

I like the concept of not treating the readers of documentation like idiots. This little card gave me the information that I needed and couldn’t know ahead of time (how much water to use, the filter looks too big but is the right size, only push the button once) without wasting my time by giving me information that I either already knew or could easily guess (I can get water from the sink, I need to use a cup). Can we use this concept in software documentation? What parts can safely be left out so that we are only highlighting the pieces that are really needed?

Miller, Lynn. Designing the User Experience at Autodesk (2009). Articles>Documentation>Technical Writing

Minimal Procedure Content: Reasoning

The procedure I wrote about creating a Twitter list uses abbreviated content. This post describes the reasoning behind and decisions made in writing the topic.

2moroDocs (2009). Articles>Documentation>Technical Writing>Minimalism

Writing Great Documentation: What to Write

Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

Kaplan-Moss, Jacob. Jacobian (2009). Articles>Documentation>Technical Writing>Software

Writing Great Documentation: Technical Style

Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot.

Kaplan-Moss, Jacob. Jacobian (2009). Articles>Documentation>Style Guides>Technical Writing

Writing Great Documentation: You Need an Editor

All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass. If you really want to produce great documentation, it needs to be edited.

Kaplan-Moss, Jacob. Jacobian (2009). Articles>Documentation>Technical Writing>Technical Editing

Quick-Start Guides Require a Minimalist Mindset

The point of a quick-start guide is, as the name says, to help the users get on their feet as fast as possible. This requires the writer to ask, “What is the absolute minimum that someone needs in order to get started?” The next best question is “What is the user going to do the most often?”

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

Five Skills for Managing Documentation Projects in an Agile Environment 

Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.

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

Quick Reference Guides Are More Useful Than a 150-Page User Doc 

I’m working on a project to boil a 150-page software user document down to a one-page reference guide that can be tacked to a CSR’s cube wall. Our goal with the one-page reference guide is to give the CSR a description of all the navigation elements and application functionality so they can quickly navigate to where they want to go without first having to trudge through the complete 150-page user doc.

Creel, Ron. Your Writing Dept (2009). Articles>Documentation>Technical Writing>Quick Reference