Content Curation: A Manifesto

A Content Curator is someone who continually finds, groups, organizes and shares the best and most relevant content on a specific issue online. I think that professional writers and technical writers should consider a move towards this role. We already search for and find the best content, sift through loads of content, discard poor content, and publish the most worthy content whenever a software release goes out. This description also sounds like something a content strategist would do as part of their analysis of the content.

Gentle, Anne. Just Write Click (2009). Articles>Content Management>Information Design>Technical Writing

Does DITA Make You Dumb?

There are at least two broad categories of technology that managers often confuse. The first is technology that replaces a particular skill. For example, the cash register at a McDonalds has technology that relieves cashiers from doing math, so they can hire people who are not skilled in math. The second is technology that allows a skilled practitioner to be more productive. For example, the computer makes it possible to write and edit text much more easily than a typewriter, but it won’t make a bad writer better.

Hamilton, Richard. Managing Writers (2009). Articles>Management>Technical Writing>DITA

How Google Wave Can Drown Technical Writers

The impending launch of Google Wave is something for every technical writer to watch. Because if they have been doing their job the same way from day one, then Google Wave's undertow is going to pull them down into the surf. However, if they are embracing online collaborations tools, instant messaging, and related technologies then they are going to think Google Wave is game changer for technical communications because it offers a new range of communications and collaborations options.

Kelly, William T. TypePad.com (2009). Articles>Writing>Technical Writing>Social Networking

What Are the Characteristics of a Good Technical Writer?

Most writers do not set out to go into this field, but more likely happen into it by chance or by a series of stepping stones that naturally led them down this path. I stated that through nature and nurture, people are formed to become a writer. So, what characteristics make up your average writer?

Guarnera, Tom. Your Writing Dept (2009). Articles>Writing>Technical Writing

Open-Source Tech Writing: The Time is Now

We are all going to have to collaborate like never before. Everyone should select at least one area of interest and specialize as best they can. Then we will need to start meeting and sharing information. Immediately. There are several ways to do this, I believe.

Norris, Julie. 2moro Docs (2009). Articles>Collaboration>Technical Writing>Open Source

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

White Paper Writing: Strategies for Success

White papers are a fundamental part of your marketing arsenal. And if you think technical writers don't need to worry about marketing, read on to see why white paper writing is an essential skill, and how to turn a ho-hum paper into a killer communications tool.

HelpScribe (2009). Articles>Business Communication>Technical Writing>White Papers

How To Use An Apostrophe

A clear, well-illustrated guide to when one should (or should not) use an apostrophe.

Oatmeal, The (2009). Articles>Writing>Grammar>Technical Illustration

Romancing the Reader    

Diane Wylie is not only a technical writer but also a writer of historical romance novels. Read how the two types of writing compare and how they differ.

Ebrahimi, Tara. Intercom (2009). Articles>Writing>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

Why Technical Communicators Should Help with Product Text

A huge problem for projects is the lack of a common language between the developers and the users. When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things.

Minson, Benjamin. Gryphon Mountain (2009). Articles>TC>Technical Writing>User Experience

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

What Are the Characteristics of a Good Technical Writer?

Technical writing is the process of taking very technical information and processing it so a larger group of readers can understand. This involves strong writing skills, understanding the technical inputs and a creative way to display this information for the reader.

Guarnera, Tom. Your Writing Dept (2009). Articles>Writing>Technical Writing

The Process of Technical Writing

The technical writing process consists of four main phases. These are planning, writing, delivery, archiving. These phases are not necessarily set in stone and some variations do exist. Every writer is different and they each have their own way of writing that is distinct.

Hunt, James M. Technical Writer Blog, The (2009). Articles>Writing>Technical Writing

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

How Soon is Now?

One common complaint a lot of technical writers have is that they aren’t included early enough in lifecycle of a project. The downsides are that by the time work hits your desk you don’t have a full picture of who the customer is, why they want whatever it is you are building, and how they want it provided to them. All of which directly impacts the information being created.

McLean, Donna. One Man Writes (2009). Articles>Project Management>Technical Writing>Collaboration

Top 10 Technical Writer Annoyances

The life of a Technical Writer is far from boring. Days spent typing away at a keyboard are often disturbed by the rigours of the corporate world. I was reminded of this earlier today when one of my team, a relatively new recruit to the world of technical authoring, discovered that occasionally being kept in the dark can be annoying. In honour of this momentous occasion, I offer to you for your delectation my own top ten ways to annoy a Technical Author.

McAndrew, Colum. RoboColum(n), The (2009). Articles>Writing>Technical Writing>Collaboration

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

Janet Swisher on FLOSS Manuals, Open Source, and Book Sprints 

Janet Swisher, who’s worked in technical communication since 1999, is an Information Developer for a medium-sized software company. Her specialist areas include online help, tutorials, API documentation and programmer guides. My “techie” cred is that she “can read code well enough to avoid asking obvious questions, and write code well enough to be dangerous.”

Walsh, Ivan. I Heart Tech Docs (2009). Articles>Interviews>Technical Writing>Open Source

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

Change Management – An Underestimated Success Factor 

Although the creation and translation of technical documents are essential parts of the product lifecycle they still play a subordinate role in most international organizations. Many companies are therefore leaving these tasks to an outsourcing provider. To ensure a smooth collaboration and guarantee high quality technical documents, the outsourcing process needs to be planned and supported thoroughly.

Grosser, Sabine and Rob Heemels. TC World (2008). Articles>Content Management>Outsourcing>Technical Writing

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