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:

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.

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.

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.

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.

Preparation

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.

Meetings

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: http://www.adobe.com/products/photoshoplightroom/
 
Microsoft PhotoSynth: http://photosynth.net

Foldersizes: http://www.foldersizes.com

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:
http://www.stephenfry.com/media/

A Way With Words

KPBS Radio in San Diego
http://www.waywordradio.org
http://feeds.waywordradio.org/awwwpodcast

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

In this, the second in a series of three podcasts, I talk to my 17-year-old daughter, Martha Christie about how she uses computers at school and at home.

Of online help Martha says:

"Those things drive me crazy. I don't think I've ever actually used any of those help systems for anything on the computer. I just don't find them useful at all.
...
There's so much writing to read and I hate that kind of thing. It's like ... if you get like a help manual with something you just throw it away before you start
...
I just can't read through it all. I'd rather just try it and then if it goes wrong I just scrap it and start again."

On the most effective way of learning, she says:

"If you want to learn something, asking a person is the best way to do it."

"I don't think I just want to be told the answer ... Getting something explained to you and getting it shown to you is different from just getting told an answer. Like if I asked a teacher for help and they just told me the answer, I wouldn't be like: 'Oh that's great, thanks' ... The best teachers don't tell you an answer - they tell you how to find the answer yourself."

She makes an interesting point about how when she wants to do something on the computer she'd naturally try and use one of the applications that are already on the computer - even if it wasn't purpose built for the thing she wanted to do - rather than search for, download and install a new application from the Internet.

I also found it revealing that she wasn't aware that most help systems for applications have an index and a search facility.

She didn't like the idea of help videos, because she wouldn't want to sit through a whole video to find out how to do something.

Finally, she's also the only person I know who's ever had anything good to say about the Microsoft Office Assistant dog. 

One of the software applications mentioned in the interview is:

Painter Classic
Metacreations Painter Classic came bundled with a Wacom tablet I bought years ago. Used with a drawing tablet it was a very impressive bit of software. Corel bought Metacreations and the latest incarnation of that software is Painter X (i.e. version 10).

http://www.corel.com/servlet/Satellite/gb/en/Product/1166553885783

This is one of the paintings Martha created using Painter Classic, in 2003, when she was twelve:

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

In this, the first of a series of three podcasts, I talk to my mum, Margo Christie about why she decided - quite recently - to buy herself a laptop. She describes how she learned to use a computer and what she uses it for now.

The books mentioned in the recording are:

• Easy PC: How to Use Your First Computer by Kenneth Mole
• The Internet for the Older Generation by Jim Gatenby

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Blaise Pascal: “I’m sorry this letter is so long, but I did not have time to make it shorter.”

First, Graham talks to Mike Hamilton from MadCap Software about recent and future software releases and some of the new features and improvements in Flare 4.

Andrew Jackson of Pacific Blue Solutions gave a presentation on information mapping. He gives an overview of what information mapping is all about, why it’s relevant for technical writers and how you go about learning how to use information mapping.

In the final segment of the podcast, Graham gets “an assorted bunch of tech authors” (John, Chris, Katja and Paul) to share their thoughts about the conference and to discuss technical authoring in general.

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

OK, I know this has nothing to do with technical writing. But I like Bob Dylan and, hey, everyone needs a break from tech writing for a while (or for 12 months, and counting, in my case).

From what I've heard so far it's pretty good stuff but very familiar - very like the stuff he's done over the past years. Not surprising really. It is the stuff he's been doing over the past few years. It's more outtakes and tracks that didn't get used. But don't dismiss it for that. In true Dylan style, the tracks that didn't get used are sometimes better than the ones that did.

The YouTube video below is one of the tracks off the album.

I also came across a great Dylan podcast recently. It's not really a podcast though. It's a radio program that's been split up into a series of short podcasts. It's presented by Patti Smith (yes, the Patti Smith), who sounds very cool, and it has lots of great guests. Two problems with it though:

1. Like most music podcasts, you only get 30 seconds or so of each song.

2. There are only 19 episodes.

http://blogs.legacyrecordings.com/podcast/category/bob-dylan-podcast/

I looked at moving to a new hosting solution, but it was going to cost me $120 a year, and I've still got a few months left with Euro-Reg before I need to renew. Then I remembered about SkyDrive - part of Windows Live. Because I have a Hotmail account going back donkey's years I automatically have a Live account that gives me 5 GB of space for free.

So the solution to my problem is to put my MP3 files on Sky drive and just redirect traffic to the new location of those files.

Adding the files is easy. Just sign into Windows Live, go to SkyDrive, click Add files:

Once you upload files, you need to discover what their URL is. Unfortunately, they don't all live in their own directory. So, for example, I created a folder called podcasts, but the URLs of the files in that folder don't contain a podcasts directory which means I can't just redirect everything in the podcasts directory on my Web server to the podcasts directory on SkyDrive. Unfortunately, you can't rely on any part of the URL being the same for different files. This means you have to redirect each one individually. This stinks and we can only hope Microsoft realises this and fixes it. For now you've just got to work with what you've got.

Click on the icon for one of the files you uploaded. This displays it on its own page. Right-click the icon on this page and copy the location of the file. This will give you an ugly big URL like this:

http://ubpq3q.bay.livefilestore.com/y1prhoUMaUaRKTKYapF5RrPEgkMKc5XUgMd4tWocxrw5LDC0oWaw5IhRTBE_jSZOcKZUvzwwlhh9vs/ITauthor-podcast01-01Dec2005.mp3?download 

Remove the last bit. The long ID string identifies the file so you don't need the file name. This reduces the URL to something like:

http://ubpq3q.bay.livefilestore.com/y1prhoUMaUaRKTKYapF5RrPEgkMKc5XUgMd4tWocxrw5LDC0oWaw5IhRTBE_jSZOcKZUvzwwlhh9vs

Now you've got the URL, all you need to do is add a Redirect statement to the .htaccess file in the Web root directory of your Web host. This is a single line taking the form:

Redirect <old directory/file> <new URL>

Where the old directory or file is denoted as a path relative to the location of the .htaccess file.

So, to redirect the file  ITauthor-podcast03-16Dec2005,mp3 to its new location on SkyDrive I added:

Redirect /wp-content/uploads/podcasts/ITauthor-podcast03-16Dec2005.mp3 http://ubpq3q.bay.livefilestore.com/y1pC8IalwMyNgTVgzoON30m5vmKc0gRTei4qqcoQF88Nkbd1Oivca-2OmkaXPJr2kEK5WCDGzf82ns

Annoyingly, you need to do this for each file. What would have been nice would have been if my SkyDrive podcasts directory had a URL like http://alistairchristie.spaces.live.com/podcasts, then I could have done:

Redirect /wp-content/uploads/podcasts http://alistairchristie.spaces.live.com/podcasts

and all my podcasts would be picked up from SkyDrive without having to edit the .htaccess each time I add a new one.

Anyway, for now it saves me having to fork out cash just for more disk space.

I talk to Mike Hamilton from Madcap Software about the newly released version 4 of Flare. He describes a lot of the new features and explains the relationship between Flare and Blaze. Mike also mentions the work currently underway at Madcap to produce a DITA version of Flare.

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Writing tips

1. Copying and pasting formatting in Microsoft Word.

   Select some text that has the formatting you want to copy.

   Press Ctrl + Shift + c.

   Select the text you want to apply the formatting to.

   Press Ctrl + Shift + v.

2. Keyboard shortcut to choose a style in Flare 4.

   Press Ctrl + h to bring up a style popup while you are editing text.

Application recommendations

Windows Live Writer

Podcast recommendations

The Definitive Word
Includes liberal use of the f word. Is that the definitive word?

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Just a quick note to say I'll be attending the ISTC Conference in Nottingham next week. I'm not known to many (any?) of you, but I plan to get as many faces to blog names as possible while I'm there. So on that note, who else is attending? I hope to grab as many people as possible for impromptu, informal chats that may form the basis of a future podcast. If you'd be willing to donate 5 minutes of your time and insight to the ITAuthor podcast I'd love to hear from you.

When I return I'm sure I'll provide a round-up of the conference either in here or on the podcast itself. Alistair has been away at the UA Conference this week and may provide an update himself when he gets back.

We had some listener feedback about the Podcast on being the sole TA in an organisation (Being the only tech writer - Podcast #13).

Paul Welsh, a Technical Writer from Nebraska, USA, raised the following point:

"One thing that I don't think you mentioned is that there's no one to talk to when it comes to
your job. Not a big deal, but I've noticed it a few times lately as I evaluate tools and there's no one else here who would really get it, or be interested in the discussion."

It's a good point, and one that I feel is actually a big deal despite what Paul suggests. Beyond the evaluation of tools and procedures - something that demands a peer for meaningful discourse - the actual discussion of work to be done and requisite peer review are just not there.

For someone as new to the vocation as me - I mentioned in the Podcast I've been a Tech Writer for 2 years now - the absence of peer review is a knock to both confidence and, inevitably, quality. The fear of not producing a meaningful piece of work is bad enough without the added burden of knowing that, without peer review, mistakes and bad habits aren't being identified and dealt with.

I've offered before that Tech Writers can feel like we're considered last and least in the list of priorities in an organisation, and this feeling is only emphasised when you're flying solo.

However, Geoff Hart's article on Why do I need a technical writer? makes a good job of listing the very specific reasons a skilled Tech Writer is an important addition to any organisation.

In particular, his first point in reducing support costs:

"Technical writers think of the task from the user's perspective, not the designer's perspective. Thus, they explain better how users can reach their goals."

Which brings me nicely to the solution I found for my dilemma - conscript one of the Testers as a pseudo-reviewer.

Any software house worth its salt will have an internal team of quality assurance testers. Testers, like Tech Writers, have an inherent eye for detail perfect for finding any error in that tricky procedure you wrote or with the delivery method you chose (broken links in a series of Online Help Web pages for example). More importantly, testers are also looking at the tasks in the software from a user's (and a usability) point of view which, as Geoff states in his article, is a vital Tech Writer trait.

While Testers and Tech Writers have different sets of skills, they nonetheless both share the same attention to detail required to perform their designated function as well as an interest in the tools and procedures needed to "get it right".

I'd never advocate this as a permanent solution of course, but if you find yourself missing a spare Tech Writer or two and are on good terms with your QA staff, relying on their keen eye is a good stop-gap.

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Simplification * Keep documentation just simple enough, but not too simple * Write the fewest documents with least overlap Determining What to Document * Focus on the needs of the actual customers(s) of the document * The customer determines sufficiency Determining When to Document * Iterate, iterate, iterate: * Update only when it hurts General * Treat documentation like a requirement * Require people to justify documentation requests We also also discuss our writing tips, software recommendations and podcasts we've been listening to. Software we mentioned:

fileinfo.net

writerriver.com

Keepass

Podcast recommendations

The Penny Arcade Podcast:
  RSS feed: http://www.penny-arcade.com/padlc.xml Dan Carlin's Hardcore History: RSS feed: http://www.dancarlin.com/dchh.xml

Other links

Testing documentation: http://www.onemanwrites.co.uk/2008/08/07/testingdocumentation/ The Almighty Thud by Martin Fowler: http://martinfowler.com/distributedComputing/thud.html

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

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

Subscribe to the podcast:   http://feeds.feedburner.com/itauthor

What follows below is just a test to check I've got a fix for it.

So I've resubmitted the RSS feed and hopefully it will show up again soon. Looking for the podcast yesterday just reminded me how bad the iTunes is at helping you discover new podcasts. Basically it's okay for the most popular podcasts in each category, because these get listed, but there's no way of finding anything else unless you happen to know what you're looking for and can search for it by name - which makes you wonder how any other podcasts can shift the incumbent most popular ones when nobody can find anything else.

I'm a huge admirer of the iPod user interface, but the interfaces for the iTunes application and the iTunes Music Stores are really very poor. The store looks nice, but it's not nice to use. The iTunes application doesn't even look nice.

Anyway, for my own reference, I came across a couple of useful tips:

1. If you have iTunes installed, clicking the following link pulls up the ITauthor podcast page in iTunes:

http://www.itunes.com/podcast?id=289204946

2. To ping iTunes to tell it to update from the published feed, click:

https://phobos.apple.com/WebObjects/MZFinance.woa/wa/pingPodcast?id=289204946

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.

Subscribe to the podcast 

The point is that you only get to choose from what happens to be available within that little time slot. Despite the fact that this is the place where you're going to live for the next few years, maybe many years, you have to choose from the few properties that happen to come up for sale right when you've looking.

Filling a position within a company is a bit like that. As the recruiter, you've got to choose from what's available. And if you've got a good recruitment agency working for you, and you're lucky, you might just get some great candidates applying. Now what you've got to watch out for is that you don't blow your chance of getting a great candidate take the job.

A great place to live will be lived in for years and years. The people who live there will be in no rush to leave. So that house maybe only comes up for sale once every twenty or thirty years. And when it does, it'll be sold in a week at the price the seller wants to get. If you take a week off from your house searching, you might miss it. If you see it and love it, but you hum and haw about the price and then decide maybe you'll be able to bid low and steal it, then you'll miss out and live to regret it. I'm speaking from experience here. I still remember a fantastic house in Portobello I wish we'd bid more for.

Similarly with great candidates for that role you need to fill. The really good tech authors or developers or testers - if they're looked after by an employer and nurtured in their careers - maybe only only come on the market once in ten years.

As the recruiter you've got to make sure that you remember that the great candidate is not desperate to have this job you're trying to fill. The interview should not be like an interview down your local nick: "We ask the questions sonny!" This is a two-way trading of skills, experience and labour in return for a great working environment, interesting work to stimulate and stretch the candidate, and a great package of benefits (not just cash, but a decent spec laptop, up-to-date software, no skimping on the budget for software and books, a work-from-home policy, food if you have to work through lunch or in the evening - all the kind of stuff that avoids people feeling like they're just working for the man).

I've been recruiting for a new tech author recently and I always try to remind myself, before I go into an interview, of the one that got away. The candidate who shone out as an obvious big asset for the company, who I failed to sell the job to, and when I offered him the job he turned it down. Hiring and firing are two of the most important things to the health of a company - especially for a fairly small company. For a company of ten thousand, one bad hiring doesn't have a huge impact unless it's at director level. For a company of a hundred, one bad hire at any level will hurt, and one great hire will make a positive difference that will ripple throughout the company. For that reason, letting a great hire slip from your grasp is a serious offence but an offence for which the offender is never punished.

As a recruiter your job has two imperatives:

1) Make sure you choose the best person for the job. There may not always be a great candidate, you may have to just choose the best of the good ones. But you've got to make sure this person is right for the job and right for the company. There are many thousands of pounds at stake here. Chances are the hiring decision is the biggest single purchase you'll ever make on the company's behalf. Spend it like it was your own money.

2) Make sure you don't miss out. In any job interview, the candidate is selling himself and you're testing and judging him. But remember he is testing and judging you too. He knows a bit about the company - knows enough to think that maybe it might be a cool place to spend most of his waking hours for the next few years, but he doesn't need to come and work here and it's up to you to sell him the job and the company. Why is this a great place to work? Why is it such an interesting job? If you can't answer those questions convincingly to yourself you shouldn't be conducting the interview.

Job interviews are for both sides of the table, but all too often - especially when it's several of you versus one candidate - the interviewers forget that there needs to be give as well as take.

Personally I try to avoid overuse of set questions. I prefer conversations to stock questions and stilted answers. And if the conversation is heading in an interesting direction and you're getting to know the candidate, then keep it going with ad hoc questions. Interviewers who rigidly confine themselves to a set of prepared questions on the grounds that everybody must be treated identically, are merely depriving themselves of getting to know the candidates and therefore getting the kind of information that will help them identify the best person for the job.

Two things to avoid as an interviewer are:

1) Setting a time limit to the interview. Sometimes you'll know someone is right within the first ten minutes. If you know this beyond doubt, the interview shouldn't take long. Sometimes you'll know someone is wrong within the first ten minutes. If you know this beyond doubt, you should start wrapping things up immediately. I don't like being rude to people, but continuing an interview when you know you're not going to offer them the job is dishonest. However, sometimes an interview just needs more time than you'd expected and, in that situation, if you need more time, take more time.

2) Saving candidate questions to the end. If you've spent two hours firing questions at a candidate and then you allow them to ask a couple of questions, you haven't really bought into the idea that this interviewing business is a two-way thing. If it's a great job and she is a great candidate then you should be as keen to hire her as she is to get the job, and the questions/answers should be pretty evenly numbered from either side (except the candidate is on your turf so, inevitably, and rightly, the interview is going to be led by you).

Never allow the situation to arise where you go away having found out all you need to know about the candidate and happy that you can offer the job to someone who you are confident will be great in the job, while the candidate has gone away unsure what the job really is, not convinced there's enough to keep her interested and fulfilled, and doubtful that the working conditions will be any better than those she has now. If all you do to a great candidate is convince her that she's much better off where she is now than she'd previously thought, then you've failed big time.

Take it from me, I've made that mistake once. Never again. I hope.

At around the same time some of my domain names came up for renewal and when I was renewing itauthor.eu with Euro-Reg.com I decided, on the spur of the moment, to buy a hosting package and move everything onto their servers. You may have noticed that, at the time of writing at any rate, the URL for the site is .eu rather than the usual .com.

Things may change because I subsequently realised that Euro-Reg only allows me 500MB of space, which isn't enough to put everything up that was originally on my site (so you may notice some missing pics etc.). I think I might move everything over to Dreamhost, but for the time being it's working OK where it is and it means I can save a bit of electricity by turning off my Web server.

If you've visited before you may notice that the site runs a little faster than before - not a huge amount though, which is a little disappointing given that I got a tiny upload speed from Sky.

The downside of moving things to Euro-Reg is that I have no command line access and I have to move files via FTP. I'd forgotten how slow and arduous FTP is. I'd got so used to using WinSCP for putting stuff on my Web server. I'd kind of consigned FTP to history and thought I'd never use it again. Funny how things turn around.

However, the big gain from moving my WordPress blog onto someone else's server is that - for reasons unknown - the "Next/Previous" links in WordPress that had never appeared before now work just fine. I'd spent ages in WordPress forums trying to get these links to show up, without success, so it's nice that the site is now much more accessible and you can get more than 5 search results now.

This was demonstrated to me very clearly over the past couple of weeks as the bid team I've been leading worked towards the submission deadline for an extremely large tender. The original submission date was extended by 10 days and yet we still ended up hitting the submit button less than 15 minutes before the closing time.

As bid team manager one of my main tasks has been keeping people supplied with work and instilling a sense of urgency. Apart from finalising pricing, we could have had everything finished, polished and ready to go days before the deadline, but even the day before I was having to play the bad guy, telling folks to cut the chatter to get the work done.

Fortunately, our little team - 4 of us - worked well together and had a good mix of skills. With other personalities it might not have worked so well, given that one of my team members was previously Customer Services Manager and was the person who had hired me and been my first line manager at the company, and another had Director in his job title, so they could have reacted badly, given that either of them could have been team leader. But they were both completely professional in their attitude and, from Day One, our team was a real team and not just four individuals who'd been told to work together for a few months.

So the bid went in yesterday: four months' work, 24 separate documents, 904 pages. Huge relief, of course, but also - as usual with big projects that are suddenly complete - a slight sense of anticlimax. I took a day off today to celebrate and reflect on what we've achieved, and to look forward to what's coming next.

Oh, and also to write my first blog post in a long time. 

So - at least for the time being - ITauthor.com is going into hibernation. Thanks for reading/listening, if you have been.

Bye for now.

Alistair

• What kind of skills do you need to be a technical writer?
• What's the difference between an information designer, a technical communicator and a technical writer?
• Which is the worst of the "six biggest mistakes project managers make with documentation"?
• Is there still a demand for printed manuals, and if so, why?
• What does Cherryleaf offer as a recruitment company that other, bigger recruitment companies can't?
• What does the future hold for technical writers?

I encourage you to have a look at the Cherryleaf website. The monthly newsletter is well worth signing up for. There are a number of interesting articles and there's also a blog (for example, you might want to check out the post Ellis referred to on the secrets of effective technical authors). By the way, I claimed during the conversation that there's no degree course in technical writing. What I think I meant was that in all the many, many CVs I've read while trying to recruit a technical author, I've never come across a candidate who has been formally trained in technical writing. However, as Ellis mentions, Coventry University run several courses in Media and Communication. Also, Sheffield Hallam University offers a postgraduate distance learning course for a diploma in Technical Communication.

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.

Subscribe to the podcast

Why not get emailed next time I publish a podcast?
Enter your email address:

Preview

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.

Subscribe to the podcast

Why not get emailed next time I publish a podcast?
Enter your email address:

  Preview

Get in touch!

I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:
comments==AT==itauthor==DOT==com

Or just let me know you've listened in by putting a pin in the ITauthor map at:
http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.

Subscribe to the podcast

Why not get emailed next time I publish a podcast?
Enter your email address:

Preview

And yes, I was tripped up. So what ... does that make me an amateur grammar Nazi?

framemaker site:itauthor.com

This is particularly useful for WordPress blogs, given that WordPress search functionality is severely limited and, unless you know the secret hoodoo of getting WordPress to do what you want, only gives you the same number of results as the number of posts per page (in my case 5), and no way to get more results. I spent several hours this weekend researching possible solutions to get a "More results" link to appear on my results page, only to have to admit defeat. It seems like "Next page / previous page" functionality used to work in WordPress but is now broken.

So, as a workaround, use Google!

The idea is that you add in a selection of questions/answers (e.g. words/phrases in German and their English meanings, or questions about car engine parts and the answers to those questions), then you just test yourself by going through a few questions every now and again and checking the answers if you need to. I have the program set as a scheduled task so that it pops up every couple of hours and I can do a few questions, or just click Quit. The questions are randomly selected, so you get different ones coming up each time.

The installer I've put up for download comes with a default French/English data file. This presents French words/phrases. You've got to remember the English meanings. Click Next to page through from one French word/phrase to the next:

You can click English if you can't remember the word/phrase.

To add or remove  entries to/from the data file, click Feed.
 
Scroll to the bottom and add more French words and their English meanings, or click in the left, grey column to highlight a row and press Delete on the keyboard to remove it. To get rid of everything and add your own data, highlight the lot and press Delete. The Properties tab allows you to change the button text from French/English to something that suits your questions/answers.

See the Downloads page for a link to the Memory Builder installer.

So, when I do find some time (hopefully some weekend soon), I'm going to upgrade WordPress and choose an off-the-shelf theme for 2.3 that looks like it might be supported through future upgrades and stick with that, so that at least everything works, even if it doesn't work, or look, like I'd like it to.

At the moment I'm on WordPress 2.1.3 so I'm just hoping the upgrade to 2.3 is fairly painless. We'll see.

http://groups.google.com/group/alt.usage.english/msg/f615e0a4acfa21f1

My favourites are:

arse-
nal

fun-
draiser

lighty-
ears

rear-
ranged

pronoun-
cement

In a .NET appication I have a form containing several controls (lets call this MainForm). I want to allow the user to change many of the properties of this form, such as the background colour, the labels, the font, etc. To do this I have a separate form (PropertiesForm). The question is, how do I access the properties of the MainForm controls from within PropertiesForm.

You might think that it was a simple case of making the MainForm class and/or the control objects declared within MainForm public rather than private. But this isn't enough. Instead you need to declare an internal (or public) variable whose type is the name of the class you want to access (in my case MainForm) and then when you open the new form from MainForm set that variable to the MainForm form. That sounds complicated, but it's easier to show it than to explain it in writing.

Here's part of the PropertiesForm code from a file called Form2.cs:

namespace MyCsharpProgram
{
      public partial class PropertiesForm : Form
      {
            //Declare a variable for the main form:

            internal MainForm ParentForm;

            ...      

            private void buttonUpdateForm_Click(object sender, EventArgs e)
            {
                  //Change the text of the exit button:

                  ParentForm.buttonExit.Text = sExitButtonText;

                  ...
            }

      }

}

In the above code, clicking the "buttonUpdateForm" button on the PropertiesForm form changes the text of a button called buttonExit on the parent form.

Here's part of the MainForm code from a file called Form1.cs

namespace MyCsharpProgram
{
      public partial class MainForm : Form
      {

            ...

            private void linkLabelProperties_LinkClicked(object sender, LinkLabelLinkClickedEventArgs e)
            {
                  PropertiesForm PropertiesForm = new PropertiesForm();
                  PropertiesForm.ParentForm = this;
                  PropertiesForm.ShowDialog();
            }

            ...

      }

}

Here, in MainForm, I have an event handler for a link label called linkLabelProperties. When this link label is clicked we create a new instance of PropertiesForm and we set the object called ParentForm to this form (i.e. MainForm). We then display the form.

What we're doing here is passing a reference to the MainForm form into the PropertiesForm form, so that you can access MainForm objects from PropertiesForm.

The Form1.Designer.cs file contains the definition of the buttonExit button, which is declared as internal, rather than private, so that we can access it from another class:

namespace VocabBuilder
{
      public partial class VocabBuilderForm
      {

            ...

            internal System.Windows.Forms.Button buttonExit;
            ...

      }
}

I should add that if you're writing serious code this is not the correct way to do this. How you should do it is to use delegates. This makes the classes and methods much more independent and makes it much easier to maintain them in a large body of code, and to reuse classes in other programs.  

The basic principles I follow are: do task analysis by reading everything available about the feature, reading about the typical users (personas are great for this goal), searching the internet for examples of the features in use, and then interviewing people to fill the gaps in the information available to me.

Next, I start by outlining what topics should be written and if there is a set of templates available I will always use those to the fullest. I guess that my outline-first approach is why the TOC standards are important to me. If I’m editing existing content I keep the users’ goals in mind while editing.

In the list of Latest Essays on Joshua's site I noticed one called A Guide to Writing Well, which isn't aimed at technical writing but, nevertheless, lists lots of useful principles that we should keep in mind while writing technical documents. Here's a few:

• Omit needless words. Write simply and without clutter. Don’t add words for “style.”
• Avoid fancy words.
  “Never use a long word where a short one will do.” (George Orwell)
  “Look for all fancy wordings and get rid of them.” (Jacques Barzun)
  Examples: Assistance (help), facilitate (ease), implement (do), referred to as (called).
• After every sentence, ask yourself what the reader wants to know next.
• Use orthodox spelling, punctuation, and capitalization.
• Use active verbs. Example: “He was seen by Joe” should be “Joe saw him.”
• Keep sentences short.
  “There’s not much to be said about the period except that most writers don’t reach it soon enough.” (Zinsser)
• Remove laborious phrases. Why use “at the present time” instead of “now”?
• Use contractions when they sound natural.
• Write like a person and not like a scientist.

After that, have a look at your Windows Services. From the Control Panel choose Administrative Tools > Services.

If that fails to show the stuff that's starting up against your wishes, have a look in the Windows registry.

IMPORTANT: Don't attempt to edit the registry unless you know what you're doing, and always take a System Restore point before doing anything. If you do decide to change stuff in your registry you're on your own. Don't say I didn't warn you!

In the registry, go to:

HKLM\Software\Microsoft\Windows\CurrentVersion\Run

When I did this I found various stuff I didn't want (but had, no doubt, installed at some point in the past) - for example, the JEdit server, iTunesHelper (I don't run iTunes on my work PC), winVNC (I used to use VNC a long time ago but haven't touched it in ages), eBayToolbar (I rarely ever use eBay).

http://notepad-plus.sourceforge.net/uk/site.htm

As its name suggests, it's a Notepad replacement aimed at programmers. I recommended JEdit a while back, but I find JEdit is slow to load and memory hungry. Its interface is also very Java-ish, which seems like a nice change to begin with but after a while it starts to feel clunky and unresponsive and you want to get back to native Windows apps. I still use JEdit for Search/Replace, but Notepad++ is good if you want a decent text editor but don't want to pay for UltraEdit.

javascript:if(frames.length<1){alert('This%20page%20has%20'%20+%20document.links.length%20+%20'%20links.')}else{alert('Sorry.%20This%20page%20has%20frames!%20This%20bookmarklet%20only%20works%20on%20frameless%20pages.')}

The easiest way to create this bookmarklet is just to create a Favorite/Bookmark to the current, call it "Link count" and save it. Then go back in and change the properties of the Favorite/Bookmark, changing the URL to the above JavaScript and, if you want, choosing an alternative icon.

So how do I get it to autostart.

One solution was provided by my colleague Andrew Waterson:

1. Create a Windows shortcut for an SFU command console.
   To do this go into Start > Programs > Windows Services for UNIX and copy the shortcut for C shell or Korn shell.
2. Put this shortcut in the Start > Programs > Startup folder.
3. Edit the properties of the shortcut. Change its name and add to the end of the Target string the command you want to execute.
   For example, I want to run /usr/local/apache2/bin/apachectl start every time the computer boots. So the Target for my shortcut becomes:
   C:\WINDOWS\system32\posix.exe /u /c /bin/ksh -l /usr/local/apache2/bin/apachectl start

string strLogText = "Some details you want to log.";

// Create a writer and open the file:
StreamWriter log;

if (!File.Exists("logfile.txt"))
{
  log = new StreamWriter("logfile.txt");
}
else
{
  log = File.AppendText("logfile.txt");
}

// Write to the file:
log.WriteLine(DateTime.Now);
log.WriteLine(strLogText);
log.WriteLine();

// Close the stream:
log.Close();

But often you don't know how many items an array is going to need. It may vary every time you run the program. In this situation, you need to use C#'s ArrayList type. To use this you need to add:

using System.Collections;

up top of your code. You can then create a new ArrayList instance like this:

private ArrayList ResultsArrayList = new ArrayList();

Notice, you didn't have to give an elements limit to the list.

You can then add stuff to the ArrayList:

ResultsArrayList.Add(ResultRecord);

In this example, from code I've just been writing, ResultRecord is actually an array of field values. So here I'm creating a list of results, each of which contains a set of result values. I use this to capture search results where I know there's a fixed set of result fields for each search result (so I can use a simple array for each hit), but I don't know how many hits are going to come back from the search (so I need to use an ArrayList for the results set).

In the following code, to output my ArrayList of Arrays to the console, I do a for loop through each item in the ArrayList and within that (for each individual search result) I do a foreach loop to print out each item (or field) of data for that hit:

for (int i=0; i < ResultsArrayList.Count; i++)
{
    Console.WriteLine("HIT {0}:", i);
    // Note: ResultsArrayList[i] needs to be cast as a string[] before it can be assigned:
    string[] newarray = (string[])ResultsArrayList[i];
    foreach (string str in newarray)
    {
        Console.WriteLine("ITEM: {0}", str);
    }
}

The trouble with C# is that it's really difficult to Google for it. Google for "C#" and you get any page containing "C"! I've I've really got to try and remember about ArrayLists for when I do more C# stuff in 6 months or a year, to save myself trawling through pages and pages of stuff on arrays - none of which start with a simple redirection like: "If you don't know how many elements your array is going to need, use an ArrayList rather than an array."

You want to do an IndexOf search to check whether searchString occurs in chunkOfText. You want the match to be case-insensitive, but you don't want to have to convert both stings to lower case or upper case before doing the comparison because it slows things down.

Answer (in .NET):

Use the CompareInfo class from System.Globalization.

How to do it:

Add using System.Globalization; at the top of your code.

Then you can do something like

int searchResultInt = CultureInfo.CurrentUICulture.CompareInfo.IndexOf(chunkOfText, searchString, CompareOptions.IgnoreCase);

Where chunkOfText is the string you want to search through and searchString is the string you're looking for - that is, the substring. As with a normal IndexOf, this returns -1 if there's no match, or the index of the first character if a match is found.

1. Start > Run
2. Enter cmd
3. In the command console enter:
   netstat -ano|grep portNumber
   This lists any processes where the port number is included somewhere on the line.
4. Look at the first number (in the second column). If this shows the port number after a colon, this means the port is currently being used.
5. Make a note of the number at the end of the line. This is the process ID (PID).
6. Run the ps program and grep for this PID:
   ps -ef|grep PID

Example

Here I was checking what was using port 4485.

C:\Documents and Settings\Administrator>netstat -ano|grep 4485
  TCP    192.100.61.161:4485    66.249.91.103:80       CLOSE_WAIT      2444

C:\Documents and Settings\Administrator>ps -ef|grep 2444
 Administrator 2444    - -   Aug 02   -   0:16 GoogleDesktopIndex      3    5

It turned out GoogleDesktopIndex was using that port. 

ProKill is a useful little utility for Windows that helps you do this. Download it from:

http://www.white-scorpion.nl/programs/index.html

Put the pk.exe file somewhere in your PATH (you can check what's in your path by entering echo %PATH% at a DOS prompt).

You can then go to a command console and do:

pk -l

to list all the currently running processes. And:

pk -n cron

To kill all those named "cron". Works a treat.

For the other options just enter:

pk