When getting a recent set of release notes ready, I sent them to the product manager for feedback. He emailed back and pointed out the concepts we needed to emphasize with a change we were making. I struggled to work them back in to my copy without making it more than people would read.

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.

› Continue reading…

Bookmark It

Hide Sites

In my project portfolio, our release manager—the one who instituted release scrums—wants to standardize on release notes across applications. Many of the projects are in a maintenance period, so releases are planned for each project every month or two on something of a rotating basis. These releases will include small enhancements and bug fixes.

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.

› Continue reading…

Bookmark It

Hide Sites

Scrums are part of the particular flavor of Agile methodology project teams use in the portfolio I work in. The managers recently borrowed the scrum concept for release preparation because the projects in this portfolio are interrelated and often have to be released together. This means that a lot of coordination is needed so that there are no surprises for anyone.

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

Several weeks ago, Tom Johnson said on Twitter that he had decided to document software with bugs and all—essentially giving the facts—and then he would update the documentation as the bugs are fixed. A number of people replied, some of them in agreement. Tom also posted the other day on writing “fictional documentation,” admitting that he will still document how it’s supposed to work without the bugs if he’s distributing in a format that’s difficult to update or distribute.

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.

› Continue reading…

Bookmark It

Hide Sites

One of the principles of Agile development is that you work in segments of time (iterations and cycles) on chunks of functionality that can be released at the end of the segments. This encourages frequent releases, which are good for users because they get new functionality and fixed bugs more often. Obviously, the amounts of functionality and fixed bugs are smaller, but more frequent releases give a sense of progress.

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.

› Continue reading…

Bookmark It

Hide Sites