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

Conversation and Community: a review (of sorts) in about 1,700 words

Technical communication is changing rapidly. If you’re not ready for that change, it’s going to really catch you off guard. Anne Gentle's book Conversation and Community is an excellent guide to rolling with those changes, and for staying ahead of them. This article takes a close look at the book.

Scott Nesbitt. DMN Communications (2009). Articles>TC>Social Networking>Documentation

The Creative Passion

How exciting is technical writing, really?” Every once in a while, discussions in blogs or at conferences turn to that question. How technical writing is not really a calling or maybe even boring. Technical writing is my creative passion. I don’t have a recipe, but I want to share my excitement. Maybe it resonates with you, and maybe you’ll see technical writing in a different way.

Weber, Kai. DMN Communications (2009). Articles>Writing>Technical Writing

Thinking Outside the Book

The notes for a presentation (titled Thinking Outside the Book: Wikis for Writing and Delivering Documentation, that discusses the whys, the tools, and the techniques of using wikis for documentation.

Scott Nesbitt. DMN Communications (2009). Presentations>TC>Wikis>Documentation

Contributing to Wikis: A Useful Activity for Novice Tech Writers?

In this post, technical writer Milan Davidovic that contributing to wikis can help novices build skills and a portfolio. And he offers a simple roadmap for doing that effectively.

Davidovic, Milan. DMN Communications (2009). Articles>TC>Technical Writing>Wikis

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

What to Know When Switching from RoboHelp to Flare

I recently switched from RoboHelp 7 to Flare 5. I’m not the person to ask about the merits of one over the other because I don’t have enough experience with Flare yet. Because I’m coming to version 5 with my knowledge being only that which my colleagues have told or shown me, I hope to make life easier for anyone moving from RH to Flare or at least trying Flare out.

Minson, Benjamin. Communications from DMN (2009). Articles>Documentation>Adobe RoboHelp>Madcap Flare

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

A Few Thoughts on Documentation for the Power User

Power user. It’s a term that I don’t like. But there definitely are people out there who are working with the software and hardware that we document who want more than just basic information. Getting them that information can be tricky.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Audience Analysis>SMEs

Form and Function, Revisited

While I'm a firm believer in the primacy of content over appearance, aesthetics are definitely a part of drawing people into documentation and engaging them. There's nothing wrong with making online assistance or a printed manual attractive. It doesn't need to be a beautifully-designed work of art, but it should be something a little more than blocks of black text on a white page.

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

Listen to the Radio

Radio and documentation. It sounds like a strange, if not incompatible, mix. But as Scott Nesbitt explains, an ideal model for writing documentation is a good radio report.

Nesbitt, Scott. DMN Communications (2009). Articles>TC>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

LaTeX, Content, and Structure 

Structure is a key component to anything that you write. In this blog post, Scott Nesbitt discusses the importance of structure in the context of using the LaTeX typesetting language.

Nesbitt, Scott. DMN Communications (2009). Articles>Writing>Information Design>LaTeX

Sometimes, You've Got to Break the Rules 

Sometimes, 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.

Nesbitt, Scott. DMN Communications. Articles>TC>Style Guides>Writing

What’s More Important, Content or Process? 

While style guidelines can be useful for maintaining consistency across a set (or several sets) of documentation, the editors that I worked with viewed the style guidelines as sacrosanct. Any deviation, no matter how small, was punishable by a nasty email and a sharply worded note to the offending writer’s manager.

Nesbitt, Scott. DMN Communications (2009). Articles>Editing>Style Guides>Writing

Musings About What’s Really Important 

Technical communicators tend to get caught up in tools and techniques and formats. But, as Scott Abel said, It’s not about tech writing. It’s about content.

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