I decided I needed to take a step back and start over. I took some quick steps that helped me produce a much clearer and stronger message about the change being made:

1. Open a blank document.
2. Write in as brief sentences as possible the concepts that you need to get across. Boil the message down to its essential parts.
3. Revise minimally.

For example, the manual for my ASUS personal laptop contains the following precautionary information:

To prepare the Notebook PC for transport, you should turn it OFF and disconnect all external peripherals to prevent damage to the connectors. The hard disk drive’s head retracts when the power is turned OFF to prevent scratching of the hard disk surface during transport. Therefore, you should not transport the Notebook PC while the power is still ON. Close the display panel and check that it is latched securely in the closed position to protect the keyboard and display panel.

Not bad, but it could be clearer (and tighter). I would break this down into the following basic ideas:

You need to take certain actions before transporting the laptop.
These actions will prevent damage to the laptop.
First, turn off the laptop.
The hard disk drive’s head then retracts to prevent it from being scratched.
Disconnect all peripherals.
This prevents damage to the connectors.
Close the laptop securely.
This protects the keyboard and screen.

Then I’d turn this into the following instruction:

Before transporting the laptop, take these important precautions to prevent damage:

1. Turn off the laptop. When the laptop is off, the hard disk drive’s head retracts to prevent it from being scratched.
2. Disconnect all peripherals to prevent damage to the connectors.
3. Close the laptop securely to protect the keyboard and screen.

Fifty-one words instead of eighty-one, and I think the final copy is more direct. (And of course I couldn’t resist adding a numbered list.) But I got there by breaking the original copy down into its basic parts.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Clear, Common Language Leads to User Success
2. The Focusing Power of Written Monologue in Brainstorming
3. Making Learners the Teachers in E-Learning
4. Visualization Can Improve Writing
5. Editing On-Screen or Hard Copy: Which Is More Effective?

One of the challenges of standardizing on release notes is coming up with a release notes process that can efficiently turn out these documents within about a week.

My release notes include the following sections, as applicable:

• Tips for preventing and solving problems: Instruction on items that have caused some users trouble
• Enhancements: What’s new in the application
• Fixed bugs: Fixes on bugs that users have reported
• Known issues and workarounds: Open bugs or other problems that haven’t been fixed, along with ways to get around them

I attend project scrums and release scrums regularly to stay up on what’s new and what problems have emerged. Another tool I use is Atlassian JIRA, the Web app that the teams use to track user stories, development tasks, and bugs.

Here’s my ideal process for developing release notes:

1. The developers and testers keep tasks and bugs up to date in JIRA, including resolved and closed statuses. This includes having a category for each release and connecting each item to a release.
2. About a week before the release, I look at JIRA’s list of items for the upcoming release. In a perfect world, all development is done at least a week before the release, and the testers are regression-testing and developers are hardening the code. The only bug fixing they do is on bugs they introduced during the last development iteration or cycle.
3. I add items to the enhancement and fixed bugs sections of the release notes based on what is closed (or resolved) and will affect the user experience. Some fixes, like database refactors, aren’t going to affect the users, so I don’t mention them. As needed, I look at enhancement or bug descriptions and ask developers and testers for more information to determine if I should include those items and how to describe them.
4. Two or three days before the release, the product managers review the notes and give feedback. If necessary or possible, it can help to have a QA lead review them as well.
5. Within the next day, I incorporate any changes and send them back for a second review. We repeat this as many times as needed.
6. Notes are distributed through the product managers. These are internal applications, so we aren’t creating a place to post the notes publicly.

It will take some coordination with the teams to make sure that some things are happening, but I have buy-in from the program manager and the release manager. Besides, the team practices I mentioned in steps 1 and 2 are probably just good project management anyway. Different projects are doing them in different amounts, and it could only help to make our processes more standard across the portfolio.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Reveal Bugs in Release Notes, Not User Guides
2. Elements in Today's Release Notes
3. Release Scrums: An Important Resource for the Agile Technical Writer
4. Getting Involved Early Helps the QA Effort
5. A Bug-Fix Cycle at Project End Is Good for Everyone

In these scrums, we have 15 minutes or so for a representative from each project team to report on the progress of showstopper bugs, testing, problems that have emerged, and so on. They usually happen during the week or two before a release (as opposed to all the time). Then, if the release date needs to be adjusted, or if a feature isn’t quite complete, management decides what to do. They still have a final go/no-go meeting, but the release scrums keep everything out on the table.

Because technical writers enjoy surprises as little as anyone else, I get invited to these scrums. This lets me know how much time I have to put release notes together and whether there are any last-minute changes I need to make to them or to any other documentation. Since some of my deliverables are deployed with the application builds, I need to know whether to remove the updates from the build before it’s released.

These release scrums have turned out to be an advantage for our portfolio. They especially help me to stay informed. If you use some variation of Agile, I recommend release scrums. Technical writers often need every resource available to know what’s happening with the release schedule.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Five Skills for Managing Documentation Projects in an Agile Environment
2. Suggestions for Survival in an Agile Environment as a Technical Communicator
3. Elements in Today's Release Notes
4. Reveal Bugs in Release Notes, Not User Guides
5. A Bug-Fix Cycle at Project End Is Good for Everyone

After Tom’s tweet, I had to think about where I stand on this issue. My conclusion is that I tend to disagree with Tom’s philosophy here. I don’t think the long-term documentation should address the bugs. I hope my documentation won’t change much (a dream in an Agile environment, I know), so I document things the way they’re supposed to work.

One answer to this problem is release notes. I have been putting release notes out for a particular project that we release every couple of months, and the response has been positive. Users are calling support or sending emails to report bugs and make enhancement requests, and it’s nice to keep them informed about fixes or other progress on those items.

I don’t know how many people actually read release notes. I think when I applied the patches to RoboHelp 7, I read the notes to see what bugs had been fixed. I expect users are more likely to be interested in them if they have reported or at least encountered bugs and realize that the release notes give them an update. We include a section listing known issues and workarounds.

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.

I don’t think users in general expect official documentation to reveal the product’s defects. (That’s for bloggers and columnists.) The release notes help feed the conversation with the users, saying in effect that “We heard what you said about the product, and this is what we’re doing about it. We’re improving the product because of your feedback.”

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Elements in Today's Release Notes
2. Consider Users' Environment as Part of User Experience
3. Quick-Start Guides Require a Minimalist Mindset
4. Style Guides: Love Them or Hate Them?
5. Conclusions from a Conversation with a User

I’ve been working on some release notes today, a deliverable that we just decided to add to a particular project (it’s not a standard deliverable in our department). Previously, I had a “What’s New” topic in the help system, but I was usually caught up enough with getting the updated documentation finished in time for the code freezes that this topic fell to the bottom of my list of priorities. But I like the idea of having this kind of document.

This edition of release notes includes three parts: enhancements, bugs fixed, and known issues and workarounds. In the next release, I’m going to include a section on user-reported bugs and their progress. We’re not ready for that this time because we need to have a better way for obtaining a list of those items. Usually, you don’t see a list of bugs until they’re fixed. However, I think it shows the user that you’re listening when you list which bugs they reported and you’re working on but haven’t yet fixed. It may hurt a little because it says, “We haven’t yet gotten this taken care of for you.” But at least you’re saying that it’s slated for fixing.

Tom Johnson and commenters’ discussion of release notes is interesting. The conversation reinforces the fact that different managers and teams prefer different things in the release notes. For this first run, our general guideline for which bug fixes to list is to exclude the ones that are back-end problems, things that the user would probably never encounter.

(The fact that release notes are new for this project and not a standard in our department reminds one of the fact that we still have some way to go to make documentation deliverables an official part of the process. But we’re getting there.)

Something that I think is important, however, is the known issues and workarounds section. The users will encounter certain problems, and to head off frustration, we want to let them know that they can get around the problem and get the job done. It also lets the users know we’re aware of the problems and aren’t sweeping them under the rug.

On a completely unrelated note, I walked past a parking lot entrance booth today, and the worker inside was playing the harmonica. Nice. When you have that kind of job, you’ve got to find something to pass the time when nothing’s happening.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. A Bug-Fix Cycle at Project End Is Good for Everyone
2. Help Authoring Woes: Index As You Go
3. Results of a Team Design Review: A Different Context-Sensitive Help Structure
4. Switching to Single Sourcing: Not a Light Decision
5. Maybe I Was a Tester in Another Life