December 2008

ITauthor podcast #23 – Release notes

December 30th, 2008   2 Comments






0:00 / 0:00


They’re a pain to produce, and we often feel like time spent doing the release notes is time wasted, when we could have been writing more important documentation. But I’d argue that release notes are among the most important pieces of documentation we write.

In this podcast I explain why I think release notes are important. I talk about what customers expect to find in release notes. And I step through a typical release notes template.


Here’s the text of this podcast:

I seem to have been spending a lot of time recently working on release notes. And because I haven’t written release notes for a few years I’ve had to think quite a lot about the purpose of them. Specifically: 

  • What’s the point of them?
  • How are they used?
  • Who uses them?
  • What do people need to get out of release notes?

All these questions have been buzzing around my head recently, so that’s the subject for this podcast: Release Notes.

Now you might be thinking that this isn’t relevant to you, and in your current job maybe it’s not, but believe me release notes are important in some positions and you never know, at some point, you may be looking for a position elsewhere, or you might want to work as a contract technical writer in which case, sooner or later, you’ll be working somewhere where you need to know about release notes.

The first thing I’ve realized is that, out of all the documentation I produce, the release notes are the only thing that I can guarantee will get read. And they’re not just read – they’re positively scrutinized in a way that most documentation isn’t, because it’s just there for when it’s needed and as long as the customer knows that it is there then that’s generally enough. So, for instance, the customer might have sign-off requirements that stipulate that they won’t accept the software (and pay for it) unless it has: online help, a user guide, an install guide and a configuration manual, or whatever. But they won’t read these through – they just want to check them off.

The release notes are another matter. When we release a new version of our software we want our existing customers to install it – maybe because it’s going to fix some issue they’ve been having, but maybe just because we can offer better support across all our customers if they’re all on the same release – at any rate we want to avoid too wide a range of releases being in use out there. And we really want to avoid customers sticking on an old release and not budging. So an important point to be aware of is that the release notes should spell out for the customer the incentive, or compelling reason, for upgrading. On the flip side, a lack of any incentive or compelling reason in the release notes may provide customers with their justification for not upgrading.

I mentioned before that release notes are read carefully. In all my years as a technical writer and documentation manager I’ve had very little spontaneous feedback from customers. Customers are usually happy to comment on the documentation if you ask them nicely and get them at the right moment. Face to face they’ll typically struggle to give you an immediate response because it’s probably something they really haven’t thought much about. This is a good sign. Documentation is like a referee at a football game, or the umpire in tennis. If you notice him it’s usually because he’s doing a bad job. So, typically, the person you ask for feedback will delegate the job to someone who uses the software more frequently and – in due course – you’ll get some comments back. But through all my years writing manuals and creating user assistance the No.1 subject for documentation-related comments from customers is the content of the release notes.

Where I work right now our standard release notes document has been largely shaped by one of our main customers. Again: this is a good thing. If you’ve got customers taking an interest in your products and telling you what they want then you’re lucky. They’re doing some of your work for you.

You’re initial reaction, when you get a customer saying: “We need rollback instructions” or “We need to know exactly which minor release versions of the such-and-such server-side software is compatible” – you’re initial reaction might be: “They’re trying to tell me how to do my job. I’m the technical writer. I don’t go telling them how to do their job.”

This is the wrong approach. This is like sending a document out for review and then taking umbrage because your reviewers actually picked you up on some of the things you wrote. Just because you didn’t ask your customers for their opinion doesn’t mean you shouldn’t be grateful to get it.

And whereas when you get review comments back, you take a view on which comments you’re going to act on and which of the suggested changes you’re going to make – with comments from customers, you better have a very good reason for not acting on them. If you take the view that you know better than your customers then you really need to stop and think about who’s paying your wages.

So, why do customers care about release notes?

Well, maybe your customers don’t. It really depends what sector you’re working in and what type of product you’re documenting, and how those products are sold.

In my case, our customers are generally large organizations running mission-critical systems. Our software is integrated into the customer’s enterprise-wide network and in many cases the software is operational 24/7, 365 days a year – so an upgrade to the software that may result in any downtime for the system is a big deal. Likewise there are training issues for any new functionality or changes to the interface. And there’s generally acceptance testing, where a sandboxed installation of the new release is tested before a decision is made whether or not to upgrade.

Of course your customers may not be so interested in release notes. For consumer products, for instance, your customers may never bother to look at the release notes – they may not know where to find them, or care less – they might not have a clue what release notes are. But the chances are that – even in this scenario – release notes do still exist, and someone needs them even if your customers generally don’t. In some organizations the release notes may be more for internal consumption than for external reading. Your support partners or MVPs probably want to see release notes and developers who have recently been moved into the product team for this product might want to read up on what’s been happening with the product recently.

Technical writers also find release notes very useful. Let’s imagine that the tech writing resource is short. Lots of developers churning out lots of code, day in day out, making lots of new product and changes to the existing products, and not enough people documenting all that new stuff. Imagine this state of affairs persists and a product has a series of releases where the core documentation (the Getting Started Guide, the online help, the admin manual) aren’t updated. You just didn’t have the staff to update that material. Nevertheless, when times get tight and you’re cutting back on everything that can be cut back on, the last thing you stop doing is writing release notes. If you release without release notes you may as well pack up and go home. But in fact you’ve probably gone already. You’re probably working somewhere else by that point.

Anyway, let’s suppose you’ve been prioritising products A, B and C – and, as a result, products X, Y and Z haven’t had any documentation done through a handful of releases other than the release notes. And then things ease off on A, B, C and you can spend some time on X, Y, Z. The first thing, as a technical writer, that you’d go to, to give you a good idea of what had not been documented through those releases would be the release notes.

All the new functionality and important changes will be listed in the release notes. So if you’re on release 7.5 now and the last update to the online help was done for release 7.2, you can pull up the release notes for 7.3 through 7.5 and, in double-quick time, you’ve got all the details you need to scope out the work you need to do to get the help system bang up to date again.

And believe me, when you pull up those release notes and you find they’ve been written thoroughly, and you can be confident that all the changes and new stuff did make it into the release notes, it’s such a relief, because it can save you many, many hours – if not days –

of effort.

But this talk is really about the scenario I’m most familiar with, where your customers are large organizations or corporations for whom their IT system is a critical part of their operations. There are a range of reasons why release notes are important to such customers – but let’s just look at the three I touched on earlier:

1. They provide details on what’s involved in the upgrade process

2. They tell the customer what changes have been made to the software

3. They inform the customer’s testing regime

So, taking each of these in turn:

No.1 – What’s involved in upgrading the existing system?

They’ll be looking for an indication of the complexity of this task to give them an idea of any downtime that’ll be needed, whether data conversion is involved (which will play a large role in the

risk assessment they carry out for the upgrade). They need to figure out how many staff will be involved in performing the upgrade. They’ll need to cost the work and schedule it. The schedule will involve booking time from the appropriate people and working out the best time to carry out the work, allowing for the possibility of a problem occurring and having to back out of the upgrade.

For that reason they’ll expect the release notes to say something about installation (that is first-time installation), and more importantly upgrade (with details that specifically mention upgrading from the release they are currently running, so that they have confidence that the supplier has tested the upgrade path from their existing release to the current release).

And they’ll want to see roll-back instructions because they want to know that the supplier has thought about how the customer can get back to the existing version of the system if the upgrade to the new release fails.

This might sound like a lot of stuff but of course all of these things may be very simple. Chances are that installation or upgrade just involves taking a backup and then double-clicking an installer file, and rolling back might just be a case of moving the backup back into place. These things needn’t be complex, but they still need to be mentioned.

Typically, release notes have a standard set of sections and those sections appear in every set of release notes, even if there’s nothing to say. For example, you may have a New in this Release section, but it’s a minor bug fix release, so there’s nothing new. In that case you’d still have the New in this Release section, but it just says something like: “No new functionality has been added in this maintenance release.” Doesn’t sound great. But at least that way everyone’s clear.

However, sometimes the installation or upgrade process is complex. In this case these procedures may require a separate document (such as an Upgrade Guide or an Installation Guide, or both). Again, if your release notes normally have Upgrade and Installation sections, don’t leave these out because upgrade and installation are covered in separate documents. Keep the sections but just give them a one-liner pointing the reader to the other documents.

No.2 – What changes have been made to the software?

So the customer’s going to be looking for answers to the following questions:

  • Have the issues I reported been fixed?
  • What’s the scale of change?

    If there are significant changes, and particularly changes to the UI, or completely new areas of functionality then that’s going to impact my users and I may have to think about training – which means cost and inconvenience.

  • Given what’s been fixed (or not fixed) – and the likely difficulty (or ease) of the upgrade, and any retraining requirements – on balance is it worth the trouble of upgrading?
  • Do the list of changes indicate that the product being actively developed, or is the supplier just tinkering around the edges? In which case maybe I should be looking for an alternative solution.

This is the sort of information the release notes should be providing.

Point No.3 – What sort of acceptance testing needs to be done by the customer? 

So, assuming they haven’t (as a result of reading the release notes) changed their minds about upgrading, they’ll want to stick the software on a test environment and check it out. So they need to know what that environment should be (are there any changes there from the previous system?) and then, once it’s up and running, what do they test for?

Well the obvious things they’re going to test for are the new things: do they work as advertised and are they easy to use? And the fixed stuff: is it really fixed?

So, as a customer, I’d be hoping that the description of new features and fixed bugs was clear enough to allow me to try out those new features and at least spot-check the fixed bugs by trying to reproduce them. But if the bug’s not clearly described, there’s no way you’re going to be able to do that.

So I guess it’s really all about giving the customer confidence. For IT managers in charge of enterprise-side software systems, new releases carry with them the fear of the unknown. If the current release is buggy they’ll be worried about the possibility of installing something that could have even more bugs. If the current release is nice and stable, and everything’s been running smoothly, then you could forgive them for adopting an attitude of: if it ain’t broke, don’t fix it.

The bottom line is you want to help them out. By the time they read the release notes they’ve agreed to upgrade (with various conditions) so you really want them to read your release notes and feel like they’re doing the right thing!

What about the format of release notes?

We produce our release notes as PDFs. We write the document in Microsoft Word and then generate the PDF after the Release Authorisation Meeting once the software has been signed off for release and the release notes have been checked and discussed in the meeting. Often the list of Known Issues in the release notes is pulled up on screen during this meeting and reviewed there and then in terms of:

  • Are these the right issues to be declaring?
  • Can we release with these bugs in the software?

We use Word for writing the release notes just because it’s not always the technical writers who write the release notes, so we have a Word template that anyone can use to write a set of release notes, and often reviewers want to mark their comments within the Word document (we don’t have Acrobat Professional – so people don’t have the ability to mark up or add comments to PDFs). But really I don’t think it matters so much what you use to write your release notes, or the format of the document you give to customers. A lot of companies use Web pages and that’s good – and it’s perhaps a way we’ll go in the future.

When I joined the company I work for now we used to send some release notes out as plain text files. And there’s nothing very wrong about that, except that a nicely formatted document is easier to read and looks much more professional. As I said before, the release notes are partly about inspiring confidence, and for me plain text release notes gives the impression this is bedroom coder software.

Publishing the release notes as Web pages and hosting them on your own Web site has the benefit that customers and staff always know where they are and can refer to them at any time. For example, when there’s a new release a customer might want to review the previous release notes particularly if they’ve missed some releases, and they want to reassess all the features and fixes in the releases they skipped as well as in the new release. It also shows prospective customers that you’ve got the balls to publish the release notes, complete with known issues, so it should help to show them that you’ve got nothing to hide.

Who writes the release notes?

I’m a technical writer, most people listening to this podcast are technical writers, so, guess what?

It’s often a technical writer who writes the release notes. But not always. Often the technical writer does an editing job on the release notes, and they’re actually written by the development project manager or lead developer. I’d say that’s’ the best way of doing things because the project manager knows what’s in this release, he or she knows what the keys themes of the release are, what the important resolved and unresolved issues are. And generally, the project manager has all the information that needs to go in the release notes.

I take every opportunity of reminding people where I work that no customer-facing documentation

should leave the building without it being edited by a technical writer. And, so often in the case, where the project manager, or senior developer, has written the first draft of the release notes, the technical writer gets to play the part of the customer – reading through the document and trying to think of what the typical customer will be looking for, or will need, from the document, and editing it accordingly.

But all too often, unfortunately, release comes along and the project manager has done nothing about the release notes, maybe they’ve dropped off the release checklist, or maybe the technical writer is just expected to produce the release notes. In this case:

  • How do you start writing release notes?
  • How do you find the information you need?
  • How do you decide which issues to declare?

Well the starting point is typically the previous release notes document. Unless this is a new product, you’d typically pull up the previous document, rename it, and start editing it. Even for a new product I often start by pulling up the release notes for a similar product. We do have a template for release notes. But invariably, I find it easier to use an existing document as my starting point.

Finding the information to go in the document should also be very straightforward, with the project manager being your first port of call. He or she may not want to write the document but, as the project manager, they’re still the authority on the release, and they should know what they want to go in the document, or at least be able to give you the headline stuff and an overview of the type of other stuff you should be looking to put in there.

If you have a project management system, it should also provide you with a list of things that need to be included as new features or fixed bugs. The other main source of information will be your bug tracking system.

What do you put in there? What do you leave out?

These questions are particularly relevant for known issues (“bugs” to you and me) that either customers have reported, or which have been discovered in house, by QA engineers, technical writers, professional services staff and so on.

If you have a small piece of software that’s fairly new, and you have a small customer base, then the product manager might want everything to be declared in the release notes. But what about if you have a big, complex software solution that might have been around for years evolving steadily, or in leaps and bounds, through each release? In this situation you couldn’t possibly list all the bugs ever reported and not fixed, because the reality of software development is that there are always bugs and you never fix them all.

Some bugs simply aren’t worth fixing. You could put half a dozen developers to work fixing all the bugs, including the ones introduced as a result of fixes to other bugs, and they could spend months and months fixing those bugs, but from the customer’s point of view – the customer would see nothing happening to the product, release after release would come out with fixes to bugs the customer wasn’t bothered about, but no new functionality.

So what always happens is that bugs get prioritized. Bugs that damage data, or amount to security issues, or which prevent you using the product as intended get a high priority. Bugs that customers raise get a high priority, especially if it’s a big customer or a customer who’s about to buy something, or an influential customer who you need to keep happy. But there are always other bugs that get spotted in house, which occur rarely, in very specific conditions, or in remote corners of the application, and if these bugs don’t really inconvenience users, and nothing bad happens as a result of the bug, then this kind of bug will be given a low priority. And if there are other, higher priority bugs to fix and customer change requests to implement, then the low priority bugs may never be fixed.

Over the years these minor bugs inevitably mount up and if you list them all in the release notes then:

a) It’s misleading because it gives the impression the software is full of bugs, when in reality most customer would never find the vast majority of those bugs. It’s also misleading because it suggests you’re going to fix these bugs and in reality you’re not. Some of them will simply never be fixed. Because the business we’re in is all about bringing value to the customer, and there’s very little value for the customer in fixing those minor bugs at the expense of building in new functionality, or new products.

b) If you list all the bugs then it becomes difficult to see the important issues for the forest of minor ones. As I said before, customers generally want to check for the issues they’ve reported and they want to know about the risk of installing the software.

So, generally you should be declaring:

  • All issues raised by customers.
  • Any other high priority issues that customer need to know about.

The latter are the kind of thing you’d be embarrassed if your customers discovered and you hadn’t already found during QA testing. These are things that weren’t severe enough to prevent the software being released, but will definitely be fixed in a future release.

Rule of thumb should be that you never declare known issues in the release notes that will just sit in the known issues list for release after release and will never be fixed, because all the important bugs will be fixed and only the important bugs should be listed.

An eagle-eyed technical writer may have reported a spelling mistake in an error message,

but that shouldn’t take up space in the release notes.

And that leads to another point about the Known Issues list. The only way an issue can be removed from this list is if it is fixed. So issue 1201 gets listed as a Known Issue in the release notes for release 2.3.1. It’s not the highest priority issue, so release 2.3.2 comes along and the issue hasn’t been resolved, so it stays in the list. But after that it is fixed. So at release 2.3.3 it moves into the Issues Addressed (or Fixed in this Release) list. And then at 2.3.4 it disappears altogether.

This is a point you should bear in mind. If you put a low priority bug in the release notes, it might have to stay there for a long time, through numerous releases.

Who reviews the release notes?

So the release notes have been written. They’ve been edited. What happens next? Who reviews the release notes?

In my experience release notes are among the easier documents to get reviewed. People generally do care what’s in the release notes.

So apart from peer review by another technical writer, the release notes should be reviewed by:

  • the product manager
  • the development project manager or lead developer
  • the release manager, if you have such a role
  • at least one Support engineer
  • at least one Professional Services representative
  • the Customer Services manager responsible for delivering this release to customers

Practice where I work currently is that we try to get the release notes out to everyone at least a couple of days before the Release Authorisation Meeting, get the review comments back in, collate the comments, and get everyone a revised copy of the release notes before they attend the meeting.

Generally, there are some further changes raised during the meeting and these get implemented immediately after the meeting, after which the PDF is generated, gets a final check and sign off and is then shipped with the software.

The release notes template

So finally, it might be useful to describe a typical release notes document. Release notes vary, from product to product, with extra sections being added as necessary. But these are the standard sections in a release notes template:

Page 1: title page – Product name, document name (i.e. Release Notes), release number (e.g. Release 2.1), company name and address, contact numbers and web site address.

Page 2: title verso – publication date, copyright information and document version number (we have a code that tells us the names of the author and editor and the date the PDF was generated).

Page 3: Contents page

Then subsequent pages contain:

  • Overview or Scope – This is simply a brief overview of what the document covers.
  • System requirements – supported platforms (e.g. Windows XP with SP3, Vista with SP1, Red Hat Enterprise Linux 5, Solaris, whatever …), required third-party software (e.g. you might need to have Word 2003 or Adobe Acrobat 8 installed for some features to work)
  • Features added – This is a description of all the brand new good stuff that’s gone into this release. This needs to be a functional, accurate description, but it also needs to be a bit of a marketing job to tell customer how this release improves the product – so you should describe the benefits of each new feature.
  • Issues addressed – This is a list of fixed bugs (but we call them issues because “bug” is a techie word and “issues” sounds less like these are things we screwed up). In our case, we do this list as a table and each issue has the reference number our Support department gave the customer (this is a reference number for a case in the SalesForce system where we log customer information), plus we have the internal reference number from our bug-tracking system. The description of the issue is as brief as possible – just enough for the customer who reported the bug to be able to confirm that the reference number matches the problem they reported.
  • Known issues – This is also a table with one row per issue – each issue having a customer ref, a Bugzilla ref and a description of the problem. The description should be as brief as possible and should give a context where appropriate – for example, if the issue only occurs when the moon is full and there’s a southerly wind, then you should include this information otherwise customers will assume the bug happens to all users all the time. Where possible you should include a workaround, but don’t include a contrived workaround for the sake of it – sometimes there just is no workaround and it’s annoying for customers if you treat them like idiots by suggesting a workaround that’s clearly not a real option for them.
  • Installation – This is for customers who are new to the product. This section might just tell them to double-click the .exe file – or might refer them to a separate document if there’s a complex installation procedure.
  • Upgrading – For customers who already use the product. Again this section might be very simple, but might involve some data conversion procedures, or it might include steps for backing up the existing installation prior to doing the upgrade.
  • Rolling back to the previous release – What happens if you attempt an upgrade and it all goes horribly wrong – or you just don’t like the new version and decide to go back to the old system?
  • Related documents – This is just a list of any other useful documents – for example, an installation guide, a configuration guide, admin guide, FAQs, or whatever.
  • Release details – This is on the final page of the release notes and it’s just a little table containing a quick-glance summary of:

    – the application name

    – the release number

    – the build number

    – the build date

    – the supported database version (if this is client-side software).

Finally you might be required to include additional standard text in your release notes, such as:

  • Disclaimers
  • A copy of the GPL
  • An anti-piracy warning and so on.


Top tips for producing release notes

Release Notes are often overlooked, or given to the junior technical writer to work on, but they’re a very important piece of documentation and worth getting right.

My top tips for producing release notes are:

  1. Get the project manager (or lead developer) to write the release notes. If they don’t write, or at least draft, the release notes, you’re only going to have to pick their brains, so it’s much more efficient all round if they do the initial work, and you do an editorial job.
  2. Use a template with standard sections.
  3. Fix a procedure and get it agreed with all parties. Once you’ve done this you can use a checklist to make sure you cover all stages, include the appropriate information, and get the document reviewed by the right people.

I hope you’ve found this podcast useful. If I’ve left anything out, or if you disagree with what I’ve said, or if you have any questions, then please add a comment in the form below.


The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Want to get emailed next time I publish a podcast?


RSS Feed RSS Feed   Add to Add to   Add to Add to Digg   Add to iTunes Add to iTunes   Add to Zune Add to Zune   Add to Google Add to Google – the technical writing podcast

Potentially similar posts

Leave a comment

Test a help topic without recompiling

December 11th, 2008

If you have a large HTML Help system, it can take a few minutes to compile.

Say you make a change to a topic and you just want to check quickly that it’ll work correctly within the compiled help. For example, the topic might reference a JavaScript file that only works in the context of the Help Viewer, so if you just open the topic in a browser the page doesn’t look and/or behave like it does within the help system. So you need to check it in the help system, but you don’t want to recompile the help system.

The solution is simple. Just open the existing .chm file, right-click the title bar and choose Jump to URL.

In the Jump to URL dialog box, enter the path to the file you want to test:

Click OK.

The topic is displayed in the Help Viewer just as if you compiled it in there.

Potentially similar posts

Leave a comment

Getting tag changes to show up in Windows Media Player

December 8th, 2008

I was tagging an MP3 file and I noticed that the tag changes didn’t show up in Windows Media Player 11. The rule seems to be that if you play an MP3 in Windows Media Player, WMP reads the tags first time, stores them in its database and from then on, if you open that same file (same file name in same directory) then WMP gets the metadata from its local database, rather than reading them off the file.

So you can force the new tags to show up by either changing the name of the file, or moving the file to a new location, but as soon as you change its name back to what it was, or move it back to the directory where it was the first time you played it, the original tags will show up again in WMP’s list pane.

I thought clearing the cache would sort this problem, but if you go to Tools > Options > Privacy and click Clear Caches, the old tags still show up.

The solution is fairly drastic. You’ve got to blow away the existing database. The effect is that from that point on WMP starts reindexing all your media as you play it – filling up its database again. Note: you don’t lose your playlists – these are stored elsewhere.

Here’s what to do:

  1. In Windows Explorer, go to the following directory:

    On XP:
    C:\Documents and Settings\$USER$\Local Settings\Application Data\Microsoft\Media Player\

    On Vista:

    C:\Users\$USER$\AppData\Local\Microsoft\Media Player

  2. Delete any files you find named CurrentDatabase_*.wmdb and LocalMLS_*.wmdb.

    If you can’t delete the files, make sure Media Player isn’t running. You may need to use Task Manager to kill off any Media Player processes that are running. For example:

    (you have to list processes by other users to see this)

Potentially similar posts

Leave a comment

ITauthor podcast #22 – Getting into the writing zone

December 7th, 2008   2 Comments






0:00 / 0:00


The voices in this podcast belong to: Graham Campbell and Alistair Christie.

stackoverflow-logo-250 On a recent StackOverflow podcast, a listener asked the presenters for tips on how to "get in the zone" as a programmer. We take up the theme here and talk about how you can get yourself in the writing zone as a technical writer, and we try to identify the things that prevent you from getting in the zone.


Do adequate research up front so that by the time you you start writing you can continue writing without having to keep stopping to check things out because you know your subject.

Avoid distractions: Email

Resist reading your emails throughout the day, as they arrive. If you *do* read your emails, resist the temptation to act on them there and then. Make a note of things you need to do and come back to these things later.

Avoid distractions: The Internet

One Web page draws you to another and another and another, and before you know it half an hour has passed. Steel yourself to stay off the Internet. When you *do* need to visit a Web page, imagine you’re back in the days of expensive metered dial-up, when using the Internet was a case of getting on there, getting was you needed as quickly as possible and getting off again. Just imagine you’re paying from your own pay packet for each minute you spend on the Web during work hours.

Listen to the right kind of music

This one’s a personal thing. I can mentally turn down the volume on conversations going on around me in the office, so that I’m not distracted from what I’m working on, until someone says my name a couple of times. But you might be the kind of person who finds that difficult and naturally can’t help but listen to whatever chat is within earshot. If that’s the case you might find it useful to put headphones on and listen to music. But it has to be the right kind of music. If you play songs you’ll be listening to the lyrics. If you play music you really like, you’ll be busy enjoying the music rather than writing. If you play mood music, you’ve got to make sure it’s the right kind of mood: if it’s too reflective or sombre it may bring you down. Graham recommends film scores (e.g. the music from the Transformers movie). I rarely listen to music while I’m trying to work because I tend to find the music gets top priority in my mind and I find time will pass and I suddenly realise I’ve just been listening and not working. One time the folks around me were chatting a lot, and too loud to tune out, so I listened to some free background music I’d downloaded for the backing track of a video demo I’d produced. The music was very innocuous and repetitive and I played it on a loop. That worked pretty well. I also sometimes use headphones with no sound just as a visual "don’t talk to me" sign. That’s pretty effective if you need to get on with work and don’t have time for chatting.

The "meh" effect

It’s Monday morning and the weekend just wasn’t long enough, or you had a bad night’s sleep, or you had an awful commute to work. You need to find something to raise your spirits, shake off those negative feelings and get yourself into a frame of mind where you want to do some good work. How you do this is going to depend on your own psychological traits and what works best for you. So if rewards work for you, you could promise yourself a reward of some sort if you get a realistically achievable amount of work done – just to get you going. For example: if I write 2 decent-sized help topics by lunchtime I’ll buy myself a slice of chocolate cake to have with my coffee at lunch.


Avoid attending meetings that you don’t really need to attend. Can someone else who’s going to the meeting report back to you with a highlights version of what was discussed? If you need to go along to the meeting can you be called into it just the bits that directly concern you and then duck out when the discussion moves on? If not, and it’s a long meeting, can you take in a laptop and do some work (even just catching up on email) while other attendees are discussing issues that don’t concern you? For all meetings, make sure they’re time boxed. If the meeting is scheduled from 2 till 3, make sure everyone knows that you’ve got something you need to do at 3. If you can, time-box contributions within meetings. We use a little application called Dinner Timer [LINK AND PIC] that gives the person raising an issue a set time to discuss that issue. It counts down on the screen and sounds an alarm at the end of the allotted time, at which point the meeting moves on to the next issue.

When you’re in the zone, stick with it

Working late when things aren’t going and you’re having an unproductive day isn’t particularly smart – better just to go home and tell yourself you’ll get in early the next day. Go home, relax, have a nice meal, have a long soak in the bath, get a good night’s sleep. But when you *are* in the writing zone, hang on in there and make the most of it.

Give yourself realistic deadlines

Nobody works efficiently if they’re working under stress. If you make your own schedules, try to make sure the dates are achievable. If someone else gives you a schedule, don’t agree to dates unless they’re achievable. It’s going to be less stress overall if you have a bit of aggravation up front renegotiating a schedule that has a better chance of success.

Don’t expect to always be able to get in the zone

When you’re working on a larger project (e.g. an iteration of development on a new product) you have more chance of getting in the writing zone and having really productive days. But for some types of documentation work that’s just not going to happen.


Recommended applications


Adobe Lightroom:
Microsoft PhotoSynth:




Recommended podcasts


Steven Fry’s Podgrams
Right now the RSS feed for this podcast is broken, but here’s a link to Steven Fry’s Web site:

A Way With Words
KPBS Radio in San Diego

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Want to get emailed next time I publish a podcast?


RSS icon  iTunes_logo Blubrry_logo feedburner

Potentially similar posts

Leave a comment

Technical writing podcast mash-up

December 5th, 2008

I was looking for an alternative to the SpringWidgets widget I used in a previous post, to put in the sidebar of this blog. The SpringWidgets one seems to need to load 100% before starting to play, which is no good because you’ve browsed to another page long before it’s finished loading.

I came across EasyListener from Yahoo:

It’s a free RSS reader/MP3 player that is incredibly easy to configure. It also set me thinking that what would be good would be, rather than just listing my own podcasts in the player, to offer a mix of other tech writing podcasts, or podcasts that tech writers might find interesting.

I investigated a few options, but by far the easiest way to do this, and configure it just how you want it, is to use Yahoo Pipes. The first half of this video shows how you do it:

Here’s the configuration I came up with:

As I’m writing this the resulting feed combines four feeds:

Yahoo Pipes takes the 15 most recent posts (except any where the enclosure is video rather than audio) and generates the following feed:

Note: The above feed actually comes from Feedburner, but it’s got the same content as the one from Yahoo. I just dropped the Yahoo feed into Feedburner because Feedburner gives me a nicer URL and generates some nice stats about how many people download and subscribe to the feed.

When I put this feed URL into the EasyPlayer code generator, I get this:

A nice easy way to help promote other podcasts that you enjoy listening to and want to share with other people.


OK, so you may have noticed that the embedded EasyPlayer widget doesn’t work. It seems to be picky about which feeds it’ll play with. It’s fine with the RSS feed for ITauthor, but it doesn’t like the output from Pipes – even though both EasyPlayer and Pipes are Yahoo creations and the feed I produced from Pipes is valid RSS (I checked).

So here’s the same feed in the old, slow-loading, and uglier SpringWidgets player:




My default browser is Firefox and, in Firefox, you can see a SpringWidgets audio player above. Internet Explorer, however, all I can see is a big white space. So my enthusiasm for audio player widgets has just taken a severe dip. I’ve messed around with both of these widgets for too much of my weekend, so I’m going to give up now. I’ll maybe try again in a few months and see if I can find one that’s less buggy.


Leave a comment

^ back to top ^

Page 1 of 11