ITauthor

My daughter Martha is going off to Guyana later this year to spend 12 months in a village teaching kids maths and science. Teachers are in short supply in Guyana, so without volunteers like those sent out there by Project Trust, kids simply wouldn’t get taught some subjects.

To go out there for a year, volunteers need to raise £4660 to cover travel, Project Trust’s running costs, etc. In order to make donating easy, and to provide a page of information to refer people to, Martha set up an account at JustGiving. It’s a really good use of the Web and I’d highly recommend it to anyone raising money for a charity.

Martha’s page is at http://www.justgiving.com/marthachristie but it expires in September, so here’s a screenshot of how it looks today:

Podcast: Play in new window | Download

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

This time round, Graham and I discuss the best way of interviewing technical writers.

Skills/attributes we mention as being things we’d look for in a candidate for a technical writer position include:

1. Evidence of solid English language skills (particularly competency in written communication)

2. A genuine enthusiasm for technology (and preferably a fascination in software)

3. Signs that the candidate would fit into the team, provide effective peer review and would be able to interact with the developers

4. The ability to review the work of colleagues effectively – and to have your work reviewed

Podcast recommendations:

The Best of MySpace – http://www.bestofmyspace.uk.com/

Mostly Tunes – http://www.mostlytunes.com/

Note: The song I play at the end of this show is one I heard on a recent Mostly Tunes show:

Be OK by Ingrid Michaelson – played here by grace of the Podsafe Music Network.

Listen to more of Ingrid’s songs.

Application recommendations:

Adobe Buzzword – http://www.acrobat.com

Google Calendar – http://www.google.co.uk/intl/en/options/ 

Tips:

Press Q on Google Calendar for a quick, natural language way of adding an appointment.

What I’m listening to:

Graham is (still) listening to the music from the Transformers movie.

Oops! – a note about the sound quality

Despite a quarter century of podcasts (if you see what I mean) I still managed to make a couple of schoolboy errors with the recording of this podcast:

1. I didn’t check the levels properly, so Graham is too quite and my mic is maxing out

2. I accidentally recorded in mono. Usually I record with each mic into one side of a stereo recording so that I could remix the levels.

So apologies if I sound worse than usual in this recording and you’re struggling to hear Graham.   

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

Podcast: Play in new window | Download

Tenders, proposals, bids – call them what you will, they’re not the standard output of a technical writer, but if you’re working for a company that wins contracts through a tendering process then you can expect to be called on to get involved in writing, editing and/or compiling and polishing your company’s bids.

In this podcast, I give a quick overview of the bid writing process, I describe some of the reasons why technical writers are an obvious choice to join a bid team and I give a few tips for surviving the bid writing process and submitting a completed bid on time.

Extract from the podcast:

As a technical writer asked, or told, to work on a bid, you may feel about it much the same way a developer feels when he's told he has to document the product or features he's just coded. You're naturally inclined to feel like this is not what you signed up for, and that there are lots of better, more important, more appropriate, more interesting things you should be doing.

However, I believe you should try not to feel like this, because it's an important job and it's one that you can probably do better than anyone else, so it's really a chance for you to shine. If you want to raise your profile within the company, you won't get a much better chance of doing so as a tech writer than working on a big contract-winning bid.

Tips:

1. If possible, don't tell people the submission date. If you let on it's a week on Friday, you might not get anything back for editing until a week on Thursday.

2. Get yourself organised. You need a system for tracking the progress of a large bid. Knowing exactly where you are with the bid, even if you're a little behind schedule, will help to keep the stress levels down.

3. Arrange little rewards for yourself and for everyone working on the bid. If you can make the job less of a chore you'll get better results. Bring in cakes when a major section is complete and make plans to go out for a night out the day the bid is submitted.

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

Podcast: Play in new window | Download

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.