When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps: Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process. Think of all the main … more »

I am constantly reflecting on the answer to this question: How can I draw upon the enthusiasm, intelligence, and skill of willing volunteers all around me to take our organization’s site to the next level? This goal mostly relates to my involvement in my organization’s technology blog, which has about 80 volunteer writers. In my post about what I learned during 2011 as a technical … more »

Some months ago I created a half a dozen quick reference guides for an application that would have a potential audience of thousands of users (after it cleared the beta phase). The size of the audience gave me hope that I would actually create documentation to be used by more than a handful of people outside the internal workings of my organization. I created the … more »

Sometimes the audience for my help consists of seniors in the range of 60 to 85 years old. The other night I attended an orientation session with users to introduce them to a new application we were releasing. As part of the orientation, I observed first-hand the challenges that seniors have with computers. Here are a few user interface problems:

Rilynn from New England writes, Tom, I notice that a lot of companies use release notes to post a list of defects (bug) that were fixed with the corresponding software release. This is something that I appreciate as a software user. I realize that I’m not the user of my company’s products, though. Also, management at my company is really against adopting this practice, seeing … more »

Coding Horror: How to Write Technical Documentation.

In a recent IT Author podcast (“Documentation and Agile Development“), Alistair Christie and Graham Campbell talk about agile development and its impact on documentation. One consequence of working in an agile environment, they say, is the need to prioritize your documentation, to deliver instructions for only the most important or confusing features. Presumably, some agile environments move so fast, you have to triage what you … more »

You know the typical scenario — the technical writer is the last one to be notified of changes to the application (be it interface or functionality), and developers hate reviewing the manuals we write. Recently a business analyst explained an interesting technique to me for not only discovering software changes, but also building rapport with developers. He said that in a previous company, he bought … more »