The latest edition to my recording is a smart new microphone on an anglepoise arm:

It's a Rode Procaster and the main difference between it and other microphones I've used is that it's a dynamic microphone. Previously I've used condenser mics that need phantom power, but I've always had problems with hiss. The Procaster gives a great sound and wasn't break-the-bank expensive. I think it's very good value for money.

You can hear it in use on ITauthor Podcast #33.

      
The other bits of kit are things I've put together over a number of years:

M-Audio FastTrack Pro

This is really just a very nice external sound card. I need one of these because the sound card on my Dell Vostro is really, really, really awful. Even just for listening to audio normally it's bad: terrible hiss and interference from the spinning of the hard disk.

I have two of these so that I can route Windows sounds into Skype, so that the person on the other end can hear sound files I play.* This is a luxury: you don't need this. And if you're lucky enough to have a good sound card you don't need either of these (but I love these things anyway - you great great sound out of them).

*I just copied Joel Spolsky's Skype setup podcasting setup: http://www.joelonsoftware.com/articles/PodcastEquipment.html
       

I bought this years ago and it's probably the bit I'd replace because it's not digital, so I lose a bit of sound quality by sending an analogue signal through this. But it's useful to have physical knobs to turn to get the levels right, and it allows me to do the Joel Spolsky method of Skype recording.
        

This is something else I've had for a few years now. It's a very simple little recorder but it does the job and is handy for recording away from home because it's small and very lightweight.
       

I wasted money on this. This is a great set of headphones: very comfortable to wear and a nice, warm, bassy sound, but I never managed to get good sound out of the microphone. As I mentioned above, this is a condenser mic and, through my setup, it always gave me hiss. It also has a thin, tinny, metalic sound that was really disappointing because this was an expensive headset.

The latest edition to my recording is a smart new microphone on an anglepoise arm:

It's a Rode Procaster and the main difference between it and other microphones I've used is that it's a dynamic microphone. Previously I've used condenser mics that need phantom power, but I've always had problems with hiss. The Procaster gives a great sound and wasn't break-the-bank expensive. I think it's very good value for money.

You can hear it in use on ITauthor Podcast #33.

      
The other bits of kit are things I've put together over a number of years:

M-Audio FastTrack Pro

This is really just a very nice external sound card. I need one of these because the sound card on my Dell Vostro is really, really, really awful. Even just for listening to audio normally it's bad: terrible hiss and interference from the spinning of the hard disk.

I have two of these so that I can route Windows sounds into Skype, so that the person on the other end can hear sound files I play.* This is a luxury: you don't need this. And if you're lucky enough to have a good sound card you don't need either of these (but I love these things anyway - you great great sound out of them).

*I just copied Joel Spolsky's Skype setup podcasting setup: http://www.joelonsoftware.com/articles/PodcastEquipment.html
       

I bought this years ago and it's probably the bit I'd replace because it's not digital, so I lose a bit of sound quality by sending an analogue signal through this. But it's useful to have physical knobs to turn to get the levels right, and it allows me to do the Joel Spolsky method of Skype recording.
        

This is something else I've had for a few years now. It's a very simple little recorder but it does the job and is handy for recording away from home because it's small and very lightweight.
       

I wasted money on this. This is a great set of headphones: very comfortable to wear and a nice, warm, bassy sound, but I never managed to get good sound out of the microphone. As I mentioned above, this is a condenser mic and, through my setup, it always gave me hiss. It also has a thin, tinny, metalic sound that was really disappointing because this was an expensive headset.

TweetDeck is a phenomenal piece of work to be created by one man. Hats off to the guy!

But why does someone go to the trouble (and it must have taken a serious amount of work) to create application as superbly usable as TweetDeck? To make some money out of it? How do you make money out of something that's given away free? Iain Dodsworth explains his plan:

The early years where he hooked up with a brilliant young engineer called Steve Wozniak and got him to design circuit boards that people still consider works of engineering artistry. The huge success of the Apple II in the late '70s when the microcomputer industry was in its infancy. His immediate grasp, on visiting Xerox PARC, of the business potential of the mouse and graphical user interface. The Apple Lisa and then the phenomenon that was the Macintosh. His sacking from Apple in 1985 and the launch of NeXT (identifying UNIX as the operating system that would allow him to continue pursuing the ideas he'd been trying to develop at Apple). The $10M purchase of a division of Lucasfilm the following year (which went on to become Pixar). The transformation of that $10M into a $585M share value when Pixar went public in 1995. The stagnation of Apple without Jobs. His return to Apple in 1996 (shortly afterwards taking on the mantle of "interim" CEO - as if anyone was fooled that he wouldn't stick around). The uber-stylish iMac in 1998 (the first of the iBrands and the fast-selling Macintosh ever). The license to print money that was the iPod/iTunes application/iTunes Music Store triumvirate. The successful replacement of the old Mac OS with Mac OS X, an operating system based on the work done at NeXT. And then in 2007 the launch of a mobile phone - but not just any mobile phone - of course it's not - this is Apple, so it just has to be, indisputably, the best mobile phone ever.

So that's all well and good. But out of all his background of success and his personal qualities - his obsession for beautiful hardware design, his extreme attention to detail, his ferocious determination to protect Apple's intellectual property, his own personal self-branding, his Wonka-esque control over what information comes out of Apple - out of all this, what is it that makes people follow Jobs, and hang on his every word, like no other business leader.

For an answer, look no further than this footage from Apple's sales conference in Hawaii in October 1983:

It's his passion, his complete commitment and his palpable belief in the importance of what he's saying that make this so totally captivating. If Jobs had been an army recruiting sergeant, looking for recruits to fight the evil Big Blue, I'd have enlisted on the spot. 

OK, to be honest, that's me. That's usually what I'm saying - or at least thinking - when it's time to ship the product to customers. And I've always told myself the reason I'm like that is because I'm a perfectionist and the reason I find it difficult to wrap something up - and say "It's good enough. Customers will get more value from getting this documentation now than from waiting a couple of weeks and getting it late" - is because I have such high standards. Turns out I'm probably kidding myself.

The lizard brain

In this video Seth Godin (author of Linchpin: Are You Indispensable?) explains why the resistance to shipping (and by shipping I mean getting stuff finished and despatched/published/released) is just another symptom of our lizard brain at work.

Seth Godin: Quieting the Lizard Brain on Vimeo

Thrash early

Another concept Seth Godin raises in his presentation is one of Steve McConnell's: thrash early. "Thrash at the beginning because thrashing at the beginning is cheap." In this context, "thrashing" means working without making any progress. The expression was coined, I believe, by Frederick Brooks, in The Mythical Man-Month where he described great beasts, long since extinct, that had strayed into a tar pit, thrashing about with all their might but not making any progress to escape their predicament.

In the following diagram McConnell illustrates the situation where a lack of process and planning at the start of a project results in an increase in thrashing, and a decrease in coding progress, the longer you spend on a project.

Diagram from Steve McConnell, Professional Software Development.

When a project has paid too little early attention to the processes it will use, by the end of a project developers feel they are spending all of their time in meetings and correcting defects and little or no time extending the software. They know the project is thrashing. When developers see they are not meeting their deadlines, their survival impulses kick in and they retreat to "solo development mode"—focusing exclusively on their personal deadlines. They withdraw from interactions with managers, customers, testers, technical writers, and the rest of the development team. Project coordination unravels.

Steve McConnell, "The Power of Process", IEEE Computer, May 1998

Among the things Scott and Chris discuss are:

• Being an advocate for the people you manage
• Getting things done means ignoring emails ("At Microsoft you either write code or you delete email")
• "No meeting Wednesday"
• Weekly or daily task setting and progress reporting
• Prime motivators for getting things done: shame and fear

Chris talks about Scott reduced posting to Computer Zen since becoming a manager. I think what he's saying is: you can be a good manager, a good website contributor, a good husband, a good father - but you only get to choose one of the above.

I'd like to think that's not true.

Please note: This video is from Microsoft's Channel 9 website and (I'm guessing) is the copyright property of Microsoft, or maybe of Scott Hanselman. Go to the original page on Channel 9 to see the video in its Channel 9 context, complete with comments.

Other links:

• Channel 9's RSS feed: http://channel9.msdn.com/Feeds/RSS/
• Hanselminutes on 9 Web page: http://channel9.msdn.com/tags/HanselminutesOn9/
• Hanselminutes on 9 iPod feed: http://channel9.msdn.com/tags/HanselminutesOn9/feed/ipod/
• This particular video: http://channel9.msdn.com/posts/Glucose/Hanselminutes-on-9-Follow-up-6-months-later-with-Chris-Sells-on-Managing-People-and-Your-Time
• Scott's audio podcast: http://www.hanselminutes.com/

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

Rahul Prabhakar writes:

Koreans place a lot of emphasis on title; it could be said that nowhere in East Asia does title hold more prominence than in Korea. Try addressing a Korean colleague of the same age group but higher designation with his name, and chances are you'll be asked to prefix a title. If you don't use a title to address someone higher in the value chain, Koreans are likely to consider you disrespectful or discourteous.
If the distance between top- and bottom-level organizational hierarchies is wide, technical communicators should resort to formal communication. If the culture encourages a flat organization, the communication automatically becomes less formal. In order to succeed in a Korean company, you must consider the hierarchy between you and the final decision maker. Allow everybody in the middle to give their opinion and be included as much as possible.
...
Korean companies don't understand why technical communication is important. For them, it's always an afterthought or an additional burden.

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

I ruminate over whether it's acceptable to use unscripted, unpolished screencasts in published documentation. Does it matter if you stumble over your words once or twice, um and ah, and have to correct your typing as you go along? Does the unscripted approach add an element of authenticity and make the whole thing more realistic and believable?

I also talk about the functionality I've been adding to our Madcap Flare projects to provide alternatives to the built-in glossary popups and expanding sections.

Finally I scan through my iPod and make a podcast recommendation. The podcast I chose was Speechification.
Website: http://speechification.com/
Podcast: http://feeds.feedburner.com/speechification 

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

Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically, they will “dip into” either a manual or the online help and at this point, if they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Rhonda asks “Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?” I think she’s onto something. I suspect that over millions of years of evolution a genetically programmed impulse to play around with things as a way of figuring things out has served the human species extraordinarily well. And so today, if given some software (or hardware), plus a set of instructions telling you how to use it, most of us will ignore the instructions and just try to start using the product.

For example, yesterday, for the first time, I was using the PushOK SVN plugin for Madcap Flare to work on our main online help project. My colleague Graham and I were both working on the same project at the same time. He’s been using the plugin for a while and I was on the phone to him asking him questions and we were working things out, in the style of: “Okay, now I’m going to click on such and such … now see if you can … did that work for you … did you get my changes?” And pretty soon I’d figured out how to do the basic stuff: check out, update, commit. Part of the thing that demanded some trial and error on our part was that the source control menu text within Flare uses Microsoft Visual Source Safe terminology rather than the standard CVS/SVN terminology we’re used to (for example, “check out” means something different).

At one point in proceedings, as we were batting things back and forwards figuring out how it worked, I joked to Graham: “You know what we really should do? We’re technical writers - we really should be looking in the help system!”

Like most people (and I quite often bore people by asking them if/when/how they consult the documentation for the software they use, so I’m pretty sure I’m part of a majority in this respect) I only consult the help system:

• If there’s no local expert around to ask
• If I’m in a situation where I don’t want to ask the local expert because I don’t want to let on I don’t know whatever it is that I don’t know
• If I can’t find the information via Google, or I happen to know the help system will do the business for me (for example, I know I can easily find details of FrameMaker keyboard shortcuts in the application’s online help, but, in contrast, I know there’s little point looking in the online help for Microsoft Word because the search facility brings back so many inappropriate results it’s far quicker just Googling for the information)

And what about printed documentation? (It’s funny, when I talk about “documentation” a lot of people still immediately think of printed books, when in fact the work we produce only rarely ends up being printed. This is probably one of the reasons some folks prefer to talk about “user assistance” – but I find that term confuses most non-IT-professionals.) Well, let’s think … when do I read the paper manual for a software application … emm … never? Since I got broadband access to the internet (back in 2003 I think), I can’t remember ever having consulted a paper manual as a way of finding out how to do something in a software application. And I used to spend a small fortune on computer books. Before my access to the internet was “always on” my home office was cluttered with stacks of computer books and binders full of printouts. In the last few years all of that stuff sat untouched, gathering dust, and it was only towards the end of last year that I finally got round to chucking it out.

But back to Sue Wooley’s article:

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

If you document software applications then you’ve almost certainly had the experience of having to document something when you know you’re writing a whole screed of instructions to compensate for a poor piece of user interface – and it’s obvious that simply moving things around the interface would make this bit of documentation redundant. That’s when documentation can be a bit soul-destroying. You of course petition the developers, log a bug or submit a change request, but in the meantime you have to document what’s there, in the full knowledge that you shouldn’t have to be writing this and the best outcome (for the end user) would result in the deletion of your work.

However, we have to be pragmatic about such things. Sometimes user interface design is just left up to some poor developer who, while he/she may be fantastically clever and a brilliant coder, has no real understanding of usability. And once a bit of poor user interface design slips out into a release it can be very difficult to repair because, unless they’re backed up by complaints from customers, requests for changes to the user interface generally get assigned a low priority. This can be very frustrating, if you’re the one who raised the issue, because some of these things can cause a lot of damage to usability but could be fixed by a little, two-minute change in Visual Studio. The hidden reality, though, is that even a quick two-minute change in Visual Studio can sap QA time by requiring changes to test scripts, updates to automated tests, manual regression testing, and so on. So a two-minute user interface change, that might prevent several hours of work by a technical writer, is often destined never to happen because of the QA cost and the feeling that any additional change carries a risk: so if it ain’t really broke, don’t fix it.

I don’t believe documentation should ever be thought of as “a complete solution in itself” (it should be an integral part of a product), but neither is it always “a backup for deficiencies in the user interface”. The products I work on are usually large, complex systems, where there’s simply too much in there to show it all on one page or in one window ­– with everything achievable within two or three clicks. Some of it just has to be tucked away somewhere to allow other things to be more accessible. As a result, you need some way of helping people find the rarely used pieces of functionality. Unfortunately you just can’t always make complex things simple within an application. Some things need explained. And as for training, well, you can develop and deliver a great training course, but what happens when someone completes a four-day course, covering lots of detail, but then doesn’t need to use a particular bit of the application until six months later?

There are good reasons why documentation is necessary. But, having said that, I’d still maintain that, in reality, for most of us, documentation is the form of assistance that you go to as a last resort, when there’s no other option.

But don’t get down-hearted. If you can create a help system that’s well targeted to provide people with the information they’re realistically going to be looking for, if you can structure it in such a way that people can find the information they need quickly without having to trawl through a list of 20 unordered search hits, if you can write concise and easy-to-read topics that explain just that nugget of information the reader needed to know … then your work is not in vain. Somewhere, some time, you’re going to help someone out. You’ll have avoided some aggravation. You’ll have reduced that day’s global curse count.

And sometimes, no matter how great the help system is, people will choose to ask a human being for help. Why? Well, because we’re social creatures and we’re often just looking for excuses for social interaction. Asking for help with the new IT system (or maybe just bitching about it generally for a while: I mean, the old system worked just fine – now I can’t get anything done!) is a chance to interact with someone, get to know the person at the next desk, chat to the girl in the next booth, make friends or maybe just kill some time.

And anyway, what’s so bad about providing a last resort? Isn’t it good to know we’ve provide people with something they can turn to when all else fails?

This is something we’ve probably all come up against at some point in our careers. Fortunately I work for a company where common sense tends to prevail and a well-reasoned argument, from any source, can be influential. But I know of lots of companies where things are very different. Documentation is often seen as just a cost centre. And when the spreadsheet guys are looking at what’s costing money and what’s winning new business it often looks like documentation is something you could do without. Because – think about it – when did good documentation, by itself, ever win one dollar of new business?

The referee was fantastic!

So, how does a documentation manager prove to the numbers guys that they need to spend money on documentation? It’s not easy. And the reason it’s not easy is partly down to the referee scenario. Think of a great football game (and I’m not talking US-type football here, I’m talking about the football the rest of the world plays). With a great game of football you’re never left talking about the referee at the end of the game. In fact after any game of football you never find yourself talking about the referee unless he did a bad job. You rarely notice the referee if he makes good decisions, lets the game flow, nips trouble in the bud, acts impartially … does his job well. You only notice him when he disallows a perfectly good goal, books the wrong person, consistently favours one team, awards a last-minute penalty when it was a blatant dive, and so on.

It’s the same with documentation. People only start talking about the documentation when it’s incorrect, badly written or absent. With documentation: no news is good news. And this is dangerous. It’s easy to cut the documentation effort because initially no one will notice the difference. The quantity and/or quality of output from the docs team will drop off, but because much of the documentation effort is for new product that’s not going to be released for a while – and even once it is released it won’t be the documentation that customers focus on first – and because the docs team will still endeavour to make sure the high priority work still gets done, it’s going to be a while before this change affects customers. In other words you can get away with it for a while before shit starts to hit fan.

The reverse is, of course, true. It takes a while for cuts in documentation resource to work through and start hurting your customers, but it also takes a while to recover from that situation once the powers that be have decided something needs to be done. In fact, after the problem has been recognised things will continue to nose dive, even after you’ve recruited replacement staff, and even supposing the replacement staff don’t need any training and can magically walk in and start being productive from week one. During this time more and more customers will be hit by the documentation-related problems. A head of steam will build up. Customers will talk amongst themselves about how difficult the software is to use. News might even spread to prospective customers. But by this time the damage that was done was done months before – and there’s no quick fix.

It’s back to the referee scenario. Not only do customers never talk about the documentation unless they’ve got something to complain about, but it’s also true to say that while documentation never won a sale, it is sometimes a contributory factor in a lost sale.

This is the point in proceedings – when you’re doing your best to recover from resource-related documentation problems, but customers are still complaining – that necks are on chopping blocks and axes are poised. And you can bet those necks aren’t the necks of the budget police who wouldn’t let you replace a colleague who left, or wouldn’t grow the docs team in line with the growth in the development team, or who “restructured” the docs team to allow budget to be reallocated to more profitable areas of the business.

Docs are important? Go on then … prove it!

This all sounds very grim. So how do you avoid getting into that mess? You might be convinced that what you do is important – but how do you convince others? How do you prove the value of what you’re paid to produce? How do you answer the question Ivan Walsh got asked: “What metrics do you use to tell if the documents are successful?”

Well I’ve been thinking about this and reading around and there’s surprisingly little out there to help me answer this question. There’s been quite a bit written about what metrics you might use to judge individual technical writers – and maybe measure one technical writer against another – or how you can assess the quality of particular documentation deliverables – for example, the number of comments that were raised during pre-publication review, or the number of documentation bugs raised after publication. But the metrics we’re talking about here are measurements of the value of the documentation effort within your company.

I came across a LinkedIn discussion that mainly concerns the micro-metrics of assessing particular documents or writers (rather than the macro-metrics of assessing the documentation effort itself) but these two quotes, I think, touch upon the bigger picture:

in the final analysis any document is only valuable if it answers the questions the user has so they are not required to make some sort of call to a support person

Keith Oxenrider

A better measure is the readers' view of the documentation. Do they like it? Can they use it to solve their problems? Does the documentation reduce the number of calls to the tech support center? Does the documentation aid the tech support center in quickly resolving client problems?

Dave Gardner

The references to support point to a possible solution.

Donald S Le Vie Jr wrote an interesting and useful article in the December 2000 edition of Intercom (“Documentation Metrics: What Do You Really Want to Measure?”), although he mainly discusses writer-specific metrics that he believes you really shouldn’t bother trying to use – for example, hours per page, pages per hour, documents released per month or per writer, errors per page, percentage of time schedule dates were met, etc. However, he ends the article with some metrics he believes are useful:

• Web-based feedback – e.g. find out what customers want more of, or don’t need, in future versions of documentation
• Customer usability of beta or final versions of documentation. Get them to rate the documentation.
• Team up with Customer Support to make sure it’s recorded when support calls are documentation related.  “Track this information over time to show the decrease in the number of documentation-related calls so you can assign a dollar figure (a quantitative measure) to any metric.”

Le Vie stresses the importance of regularly broadcasting these metrics throughout management.

Conclusion

In the LinkedIn discussion Padric O'Rouark says:

Sell “help” separate and you would find very few buyers.

That’s true, but it’s also misleading. The fact that you wouldn’t pay for something does not mean it has no value. When I buy a bed from Ikea I expect to find instructions on how to assemble it when I get it home. I wouldn’t pay for those instructions separately though. If I was expected to do this I’d just shop elsewhere. As an aside, the poor quality of Ikea’s assembly instructions is one of the things that makes me dislike the company as a whole (that and the fact they try and steer you round the whole store before you get to the checkout, rather than letting you get in, get what you want and get out).

If customer satisfaction is important to a company then the philosophy of doing only as much as you need to do to make a sale, and not one jot more, probably only works if you’re a make-a-quick-buck-and-disappear business, or if you’re competing solely on price and you’re confident customers will accept poor quality products and bad customer service just as long as the price is right.

Customer-facing documentation has no place in a cut-price or fly-by-night business. But in the software business where companies need time to grow and therefore customer retention is important, user assistance is valuable. If you’re trying to sell corporate software then the people with the purchasing power, the decision makers, aren’t the people who are going to be using the software day in, day out. But if you’re in the business for a few years then some of those people who have to use the software in their daily jobs get promoted and end up being decision makers, or at least decision influencers. If you’ve had to struggle for several years using a badly designed bit of software from Company X, that had little or poorly written user assistance, then, later in life, when you get the chance, you’re going to make damned sure you don’t let  Company X inflict any more such pain on any of your staff!

It’s hard to come up with metrics to justify the current size of the docs team, beyond all argument. Bean counters are interested in having more beans to count, so winning new deals and satisfying contracts in order to be paid quickly are things that tend to impress them. In this regard, you could look at the number of documentation requirements within Request For Proposal documents from prospective customers, or you could find out whether documentation was scored as part of customer acceptance tests? 

But other than that, what can you come up with to use as proof of your value to the company that pays your wages? Well, the source of your wages may be the key, because really it’s your customers who pay your wages and they are the only ones who can provide metrics that will convince management of the value of what you’re doing.

I started this piece by suggesting that if you sack tech writers, or reduce the proportion of writers to developers, sooner or later customers will start to suffer. If that’s true then it should be measurable. Keep a record of the number of documentation-related support calls or bad customer feedback mentioned in engineer site visit reports. Have numbers gone up or down over the past six months?

You might never be able to prove that customers are happier because of the work you do, but if you’re able to prove that customers are less annoyed with the products and increasingly able to get on with their business without calling support, then you might just be able to convince people that documentation is valuable.

In this example, all the new button does is change the h1 heading style, giving it an orange background, but you could have buttons to completely change the whole look and feel of your WebHelp – to give readers some variety – or you could add a button that darkens the window and display a lightbox-style popup containing a video of you juggling cats. You might have more useful applications for this functionality, but you get the picture: the functionality is there for you to use however you want. The trick is how you add a button and then how you make that button call a JavaScript function. After that the rest is down to your own JavaScript/jQuery skills. 

So, the following assumes that each topic page in your WebHelp calls a JavaScript file where you keep all the cool, dynamic stuff you want to do when a reader clicks around in your help files. For example, I have a JavaScript file called MyWebHelp.js that uses a lot of jQuery to do stuff, so the head element of each HTML page in my help projects contains the following:

<script type="text/javascript" src="Resources/JavaScript/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="Resources/JavaScript/MyWebHelp.js"></script>
        

To add a function button to the WebHelp toolbar
    

1. Create an image to serve as the toolbar button and save it as a .gif file.
   
   If you want the button to change on hover, or when clicked, then you can create 2 additional images for these states.
   
   These are the 3 images I used in this example:
   
        
2. In your JavaScript file add a function that you want to call when the toolbar button is clicked. For example, this function (using jQuery) adds an orange background to the h1 heading on the page (pretty useless, I know, but it illustrates the point):
   
   function makeHeadingOrange() { 
       $('h1').css('background-color','orange');
   }
3. From the Project Organizer in Flare, open the skin you want to modify.
4. Click the Styles tab.
5. Select Toolbar Item.
6. Right-click Toolbar Item and choose Add Class.
7. In the New Style dialog box, enter a name for your button class (for example, makeHeadingOrange).
   
   
8. Click OK.
9. Expand the Toolbar Item list and select your new class.
10. In the Basic properties for the class, click in the value column for Icon (this will currently be displaying “not set” as its value).
11. Click [Browse for image…] and find the button image you created.
    
    Notes:
    - When you specify an image it becomes part of the binary project data. The image file itself is not saved as a resource, like your screenshots, so you can only choose one of the existing images that have been absorbed into the project file, or incorporate a new image by browsing for it.
    - The images in this list are not sorted into alphabetical order. New images are simply added to the bottom of the list.
    
    
12. Choose images for the PressedIcon and HoverIcon properties (you can use the same image for all three states if you want).
13. Add a tooltip – for example, Make main heading orange.
14. In the Type properties for this class set ControlType to Button.
15. Set Onclick to the name of the function you want to call – in my example it’s makeHeadingOrange().
    
    
16. Click the WebHelp Toolbar tab.
    
    Your new button class is now shown in the Available list.
17. Move the button class into the Selected list and position as required using the up/down arrows.
    
    
18. In the section “Custom Javascript to include in Toolbar page”, click Edit.
19. Paste the following into the Toolbar JavaScript dialog box:
    
    function makeHeadingOrange() {
          parent.frames['body'].makeHeadingOrange();
    } 
    
    
    
    This creates a function called makeHeadingOrange which, when called, in turn calls another function called makeHeadingOrange. This second function is the one you added to your main JavaScript file in step 2 of this process. You could call them by different names if you wanted – but I think it’s clearer to call them the same thing. This second function is in a JavaScript file that’s referenced in your topic files and it isn’t directly accessible from the toolbar frame, so the first function (the one you added in Flare) is used to call it from within the context of the frame named “body”. The “body” frame in Flare WebHelp is the main frame within which the help topics are displayed. You could locate the code for the second JavaScript function within the topic HTML itself, but it’s going to be far easier if this function resides in a JavaScript file that you reference in the head of your topic pages.
    
    You can include as many custom Javascript functions as you want, listed one after the other in this dialog box. When the project is compiled, the text in this box becomes a file called Toolbar.js in the Data/<skin name>/ directory of your WebHelp output.
    
    So, if you want to, you can have lots of buttons, each calling a different function in your main JavaScript file (via the functions in the Toolbar.js file).
20. Click OK to close the Toolbar JavaScript dialog box.
21. Save your changes.
22. Build the WebHelp target output and test the results.
    
    Hovering over the button:
     
    
    Clicking the button:
     

Searching for a solution, I found an explanation of what was happening, plus a very nice little free fixer tool here:

http://forums.cnet.com/5208-7594_102-0.html?threadID=308647

All Panasonic,JVC and Canon mpeg2 camcorders that generate MOD files on either HDD or SD-card do not set the widescreen flag in the mpeg2 sequence headers in 16:9 mode. Instead they leave it as 4:3 and put the information, whether 16:9 or 4:3 was used, inside the corresponding MOI file.
        Unfortunately most video player or editing software do not evaluate the content of the MOI file and therefore the video remains in 4:3.
        I have written a small tool sdcopy that can automatically correct the 16:9 flag of multiple MOD files. In addition, it can automatically copy all found MOD files(of all subfolders) into a single target folder. Sdcopy does not modify or decrease the video quality, it just patches the headers.
        You can download sdcopy from here, its freeware:
        http://zyvid.com/smf/index.php?action=dlattach;topic=280.0;id=218

 
I’ve used SDcopy and it did exactly what I wanted: produced videos that opened up in Media Player in 16:9 and, in the process, gave the files much more meaningful file names.

Your problem may be that the Flare database for your project has got messed up in some way. The symptoms of this are that you can be typing in the editor but no characters are showing up, then, after you wait a few seconds they appear, so you go on typing, but then things slow up again.

Flare uses a Microsoft SQL Server database to keep track of the interconnections between topics. This helps prevent you screwing things up when you delete a topic – because Flare will ask you what you want to do about all the references to that topic and will convert all the hyperlinks to normal text, if that’s what you want to do.

To repair a messed up database:

1. Save your work.
2. Close the project and Flare.
3. In Windows Explorer, go to the Analyzer subdirectory for the project.
   
   
4. Delete the files in this directory.
5. Restart Flare and load the project.
   
   Flare will rebuild the database. This will take a few minutes, depending on the size of the project – during which time you’ll see lots of activity in Flare’s status bar – but once it’s done you should have a nice speedy Flare again.

The other things you can do to speed up Flare a little are:

• Disable phrase collecting (choose Tools > Options > Analyzer and remove the selection from the check box). This turns off the phrase suggestions that you see in the Intellisense popups (if you have that turned on). If you don’t use this, turn it off.
• Turn off Intellisense all together (choose Edit > Intellisense and remove the selection of Enable Intellisense). Personally, I found this feature annoying rather than useful, so I prefer to have it turned off anyway. 

And with formatting and styling it’s pretty much the same story. By using CSS, you have a high degree of control over the look and feel of your output. For example, I’m working on a WebHelp system right now and it’s been fairly straightforward to get most of the output looking more or less how I want it to look. The simple things like changing the background colours, the fonts, the icons, and so on are easily done from within the Flare application. And there are other things you can achieve by using Javascript to inject a CSS file dynamically on page load, if you want to override things in the Flare stylesheets that are injected into your output files at build time.

However, I’m painfully reminded, working with Flare again today, that one of the reasons I’m not 100% of a Flare fan is that Madcap fell short of making the styling of output 100% configurable via stylesheets.

Things like the Related Topics popups rely on Javascript, triggered by an onClick event, to add elements to the topic. This is perfectly standard, but whoever coded this decided in their wisdom to embed style information directly into those HTML elements, rather than giving everything a class name and controlling the styles from a stylesheet. In the hierarchical system that is CSS, nothing gets to overrule styles applied directly within the style attribute of an element in the HTML, so if the coder coded:

color="black"

then you you can have any colour you want, as long as it’s black – that is, you don’t get to modify the colour in your stylesheet to something more subtle, you’re stuck with the coder’s idea of what looks best for your output.

So my particular example today was that I was trying to beautify the Related Topics popup a little. Here’s what it looks like out of the box:

And I managed to modify most of it. But I just couldn’t get at that close button. It’s added directly by the Javascript. If it was in a Madcap CSS file – for example, as the background image on a div – then I could have overridden it with my own close button. But in the end I thought: sod it, if I can’t replace it I’ll just remove it. So here’s what I ended up with:

I know I’m biased, but I think it’s a big improvement. A little close button would have been nice, but I think most users know, or will quickly work out, that clicking away from the popup box makes it go away.

To style this up I used the following Javascript to add an override CSS file, which allows me to get at some of those hard-to-read Madcap styles:

$(document).ready(function(){
    ...
    //Append a link to the CSS file
    var newCSSlink=document.createElement('link');
    newCSSlink.setAttribute("href","Resources/StyleSheets/MCstylesOverrider.css");
    newCSSlink.setAttribute("rel","stylesheet");
    newCSSlink.setAttribute("type", "text/css");
    headElement = document.getElementsByTagName("head")[0];
    headElement.appendChild(newCSSlink);
    ...
});

This first line of the above code gives away that I’m using jQuery as an easy way to select and modify elements in the HTML. This just requires an extra Javascript file reference in the head of each page. If you use Javascript and you’re not familiar with jQuery, I’d strongly advise you have a look at it now!

Within my MCstylesOverrider.css file, the bit of CSS that removes the div containing the close button is:

div.MCKLinkBody div
{
    display: none;
}

Flare presents you with the old 80:20 rule. To get to a state where you’d be happy with the styling and behaviour of everything, you’d spend 20% of your time and effort getting 80% there, and then you’d spend the remaining 80% of the time finishing things off. For us pernickety perfectionists, Madcap could have made life a whole lot easier by making everything accessible and easy to change.

Message to software developers: when it comes to look and feel, less of the hard coding – please!

One reason for not declaring this information openly on the title page, was an expectation on the part of a few of our customers that each release of a software product should have its own release-specific manual – even if the release was just a bug fix release, where nothing requiring documentation was added or changed. I was determined to resist being forced into producing a new version of a manual where the only change was that “Release 7.5.2” changed to “Release 7.5.3” on the title page.

But the other (real) reason was that there had been times where, I have to admit, new releases of software went out without an updated manual, simply because of a lack of technical writing resource, and my title page coyness was driven by a desire on my part to avoid this being blindingly obvious to the customer. In this situation, you really don’t want to put “Release 9.5.0 – November 2005” on the title page of a manual that may accompany the 9.7.0 release of the software several months later.

But, thankfully, that situation has improved and earlier this year we started putting a simple document version number on the title page of our manuals:

Document version: 1

However, we ran into a problem with this. A simple version number leaves unanswered questions. Does the version number apply to that document, which gets updated throughout the life of a product, through various releases. That is, you wrote version 1 of the User’s Guide for the 1.0.0 release and when release 1.0.1 came around you didn’t write a new manual, you just made a couple of updates – so shouldn’t this be version 2? Or should it be another version 1, because it’s the first version of the manual for that particular release?

By this time we were logging all our new documents and documents updated for a specific release as records in a database. So, continuing the habit of a professional lifetime, I devised an obfuscated code based on database record for the relevant product, plus the record for the document, plus an eternally incrementing version number, to arrive at a unique identifier like:

Document version: 50.8.12

Still no date though. I was still extremely wary of openly declaring the publication date. Old habits die hard.

So, bringing things up to the present – and the reason for this blog post – my new thinking is: less obfuscation, more honesty. Right now the technical writing team is doing really well at keeping the documentation up to date. And my current belief is that if, in future, we start struggling to keep the documentation up to date, then making this obvious to the customer is probably a good thing. If up-to-date documentation is important to the customer, they’ll will raise this with the Support team, the Support team will raise that with me, and I can use that information to back up a request for more resource. If my company wants to keep its customers happy (which it does) then, in this situation, the chances are good that I’m then going to be able to get more resource when I need it.

My new plan for our title pages is to include information like this:

Document ID: 540
Revision number: 1
November 26, 2009

The document ID comes from our document database. Every time we create a brand new document or we update a document for a new release, we create a new document record and the revision number starts back at 1. Updates within a release don’t get a new document record, but the revision number increments.

We no longer need the old obfuscated code that we used to put on the copyright page, with details of who created and updated a document, because that information is captured in our database (and in SVN). The main change is adding the date. Like I said, I resisted doing this for a long time, but I’m now convinced that being open about the publication date is the right thing to do.

Having made this decision I thought it would be interesting to see what other software companies are doing. Here’s what I’ve found this evening after a quick, random and completely unscientific check of some publicly available software manuals. The following shows what document details I found on the title pages of the manuals I looked at, other than the company name, company details, product name, product release number and document title.

Citrix
No other details on title page. Copyright page included:
Document Code: June 3, 2009 (KKW)

Cisco
November 24, 2009
Text Part Number: OL-15574-01

IBM
SC09-4820-01

Oracle
E14481-01
February 2009

Adobe
No other details on title page. Copyright page included:
Part Number: 90081719 (07/07)

Microsoft Press
Traditional book publisher style title page and copyright page. No other details on title page. Copyright page contained lots of info, including ISBN, imprint numbers, names of all editors and indexer, then, at the bottom of the page:
Body Part No. X 12-41775

So what does this prove? Well it probably proves nothing, but it certainly suggests a general reluctance to declare how old the manual is on the title page – and there is still a fair amount of obfuscation going on out there.

But I’m not convinced everybody would be sure what you meant if you referred to an application crashing. So today I was looking for an alternative to “crash” and I came across the following on the LA Times website:

3 injured as LAPD helicopter makes a 'hard landing'
A Los Angeles Police Department helicopter with three people aboard made a "hard landing" in Lancaster today.

Experiencing a “hard landing” is also an expression we’ve heard regularly over the past 12 months in relation to the economy, but I must admit I’d never stopped to think that what they really meant was a crash.

I didn’t have any luck finding a suitable  “crash” alternative via Google, so I looked up the Microsoft Manual of Style where I found the following advice:

“Use fail for disks or stop responding for programs or the operating system. In content for software developers or information technology professionals, crash may be the best word in certain circumstances, but it is well worth avoiding whenever possible.”

So I asked the writer whose documentation I was reviewing to change “crash” to “stop responding”. But I’m not entirely sure. Maybe we should call a spade a spade and a crash a crash.

Think Visio is clumsy and annoying to use? Try using QMAP!

Anyhow, I had linked one diagram to another diagram as a child process, but then changed my mind and wanted to remove the link. I selected the little box that (intuitively? I think not) represents a linked diagram, and I pressed the delete key. The following message was displayed.

Now, of course, with hindsight, I should have taken my time, read the message over several times, considered its implications, thought long and hard about what I should do next and then, and only then, proceeded cautiously. Maybe I’m just too used to software that works sensibly.

Did I want to store CHILD GROUP “2” (as it so nicely called the diagram I’d actually named “Review Process”) inside the trashcan? Well, no, I did not want to store it inside the trashcan, I just wanted to remove the link on this diagram. So the answer was no. Right?

So I clicked No. Big mistake!

What this dialog box was really asking me was: “Do you want to delete this diagram?” But for some reason, the developer had kindly thought to include within this dialog box the option to delete the diagram irrevocably, without placing it in the Recycle Bin, and without bothering to offer me an “Are you sure you want to delete this?” opportunity to change my mind. One false click and a couple of hours’ work vanished into thin air.

So let’s consider some of the things that are wrong here:

a) The word “delete” is never mentioned.

b) Instead it refers to the normal deletion operation that we all know and love as “storing inside the trashcan” (“inside” mind you – not “in” or “on” or “underneath” or “nearby”, but “inside”).

b) It uses some weird nomenclature to refer to a diagram I’d already named, so it’s not clear what I’m about to “store” (or not).

c) By answering “No” to this question I am just saying I don’t want to do the thing it has offered: to store something inside the trashcan. I am not saying anything more than that. I’m just saying “No – don’t do that.” However, the software assumes that because I don’t want to do the thing it’s offered to do, I obviously do want to do this other thing: the thing it hasn’t actually mentioned, namely delete my work instantly and forever.

d) The dialog box also has two other buttons: “No to All” and “Yes to All”. However, I’d only selected one thing, so what were these “all” things. All what?

This is just the tiny, but ghastly, tip of the enormous iceberg of horrors that is QMAP usability (or lack of).

I can only hope you never encounter this application.

At the moment I’ve called this item “Friends of ITauthor”. But right now I’m the only one on it, which looks very sad. So please click the Join this site button in the sidebar and add yourself.

ITauthor needs a few more friends than just me!

.
.

The example Microsoft gives is a document with three sections in it but the PDF that you generate ends up containing Section 1 followed by Section 3.

You might have encountered this problem if you’re a FrameMaker user and assumed it was an Adobe issue. It wasn’t, it was a Windows issue.

Here's the hotfix:
http://support.microsoft.com/?id=952909

The other things you can do with the sidebar are:

• Add the link to any of the newsgroups you belong to.
  Tom has set up a “Technical Communication” newsgroup and it’s the links that get added to this newsgroup that appear on Writer River. This is great because it means you can have your own personal list and then, from that, choose who you share particular links with.
• Send a tweet about the page.
  Rather than going to your twitter client and tweeting about this separately – just write your tweet in the sidebar.
• Publish the link to your blog or to delicious.
  The sidebar has WordPress and delicious integration. In my case, I want to have my own “What I’m Reading” list in my WordPress blog. So I have a “What I’m Reading” category already set up and I have Publish2 set to select this as the default category. The good thing about this is that if Publish2 disappeared tomorrow I wouldn’t lose all my “What I’m Reading” links they way I would if I was just adding details dynamically to my site by pulling in information from the RSS feed for my list at Publish2. There is a Publish2 JavaScript widget that you can add to any Web page to pull information down from Publish2 if you want to do it that way. But by actually posting to my blog from the sidebar it means that data is saved to my WordPress database as well as to Publish2’s database.
  

So here’s how I add things to my “What I’m Reading” list. Note: the way I used to populate this list is described in this post – but it was massively complicated compared to this method.

1. When I've read a page I think other tech writers might be interested in I just go to my Bookmarks list, click the Publish2 link and fill out the sidebar form that's displayed.
2. I type in a description of what I like about the page in the Public Comments box.
3. I select the check box for the Technical Communication newsgroup.
4. The check box for twitter is selected by default - I just add some tweet text.
5. In the Also add this link to section I select the check box for ITauthor.com.  My What I'm Reading category is already selected - I just have to copy some text from the Public Comments box and that becomes a link to the article in the resulting blog post.
6. I click Save and I'm done.
   
   My blog's updated with a new post, Writer River also gets a new link entry and a tweet gets sent out to my twitter followers.
   
   Quick, easy and kills three birds with one stone. Brilliant!

Brian Eno has created an ambient music application for the iPhone. The blurb at http://generativemusic.com/ says:

Developed by ambient pioneer Brian Eno and musician/software designer Peter Chilvers, Bloom explores uncharted territory in the realm of applications for the iPhone and iPod touch. Part instrument, part composition and part artwork, Bloom’s innovative controls allow anyone to create elaborate patterns and unique melodies by simply tapping the screen. A generative music player takes over when Bloom is left idle, creating an infinite selection of compositions and their accompanying visualisations.

Fortunately, for those of us without iPhones, there’s a Flash version of it for the PC. Go to this URL, turn on your speakers and click around:

http://www.nuigroup.com/bloom/bloom.swf

Tip 1 – Entering Control-Ms in vi

When you’re editing a text file in vi and the file was created in a Windows editor, you’ll see control-M (^M) characters at the end of each line.
If you want to add a new line and you want it to show up as a separate line in Windows, you’re going to have to add a control-M at the end of the line. The ^M is a single character, so you can’t just type ^ and then type M. You might think, given the name of the character, you could just hold down the Ctrl key and press m, but it’s not quite that simple.

What you need to do, in vi, is press Ctrl+v followed by Ctrl+m.

Tip 2 – Zipping files in UNIX

Usually when I’m working in UNIX and I want to compress a file, I use gzip:

gzip filename

This replaces the named file with a compressed version of it, with .gz added onto the end of the file name. To unzip the file do:

gunzip filename

This replaces the .gz file with the original file.

However, sometimes you need to create a .zip file. To do this use the zip command, but you need to know the syntax:

zip –r outputfile inputfile

For example:

zip –r temp.zip temp.txt

In fact you don’t need to specify the .zip file extension. If you give a file name without a file name extension, the .zip extension gets added automatically.

A new zip file is created and the original file is not deleted. To unzip just do:

unzip zipfile

This creates a new, unzipped file but does not delete the zip file.

I just tried this out and the following stats for compressing a small text file suggest that gzip is the more effective compression program:

temp.txt    677K
temp.txt.gz    416K
temp.zip    504K

In pseudocode this goes like this:

<if this evaluates to TRUE> then <parse this> else <parse this>

All you need to do is replace the "then" with a question mark and the "else" with a colon:

<if this evaluates to TRUE> ? <parse this> : <parse this>

For example:

print  $trueOrFalse ? "you're telling the truth" : "you're lying";

Ignore the print command, it's not part of the if/then/else statement, it's just here to do something with the outcome of that statement.

The expression immediately to the left of the question mark is evaluated. The expression between the question mark and the colon is parsed if the expression evaluates to TRUE, otherwise the expression immediately to the right of the colon is parsed. So in the above example, either "you're telling the truth" or "you're lying" is printed, depending on whether $trueOrFalse is ... you guessed it ... TRUE or FALSE.

But perhaps a more common situation is toggling the value assigned to a variable. For example, toggling between TRUE and FALSE:

$trueOrFalse = $trueOrFalse ? FALSE : TRUE;

Here's a practical example of the use of if/then/else one liners. There's two in this chunk of PHP. The scroll box list below the code is the kind of thing this PHP produces.

<div style="overflow:auto; height:100px; width:300px; border:3px groove #DDD; padding:0">
<?php
    $alternateLine = FALSE;
    while($presidentsArray) {
        print "<div style=\"background-color:";
        print $alternateLine ? "#F5F8F9" : "white";
        print "; padding-bottom: 1px\"> &nbsp; &nbsp; <a href=\"someURL\" title=\"This link goes nowhere\">" .
          $presidentsArray['name'] . "</a></div>";
        $alternateLine = $alternateLine ? FALSE : TRUE;
    }
?>
</div>

But Yahoo quietly choked it and hoped that nobody noticed. I’m not sure why they would do this. I’m sure they could handle the bandwidth of people pulling down the Shockwave file off some server that had been left to serve up the old webjay.org pages. Maybe someone at Yahoo just pulled the plug on that server and not enough people have complained. I wish I’d gone and grabbed the files while they were still there. I looked at archive.org but the URL was never spidered.

So I’m going to have to find another solution, but it won’t be for a while because I know there’s nothing quite like it out there, so I’ll have to do some switching around and PHP-ing to sort it out.

It’s symptomatic of the Web though: it seems like a solid, reliable structure, but it’s really entirely transitory and kept in working order by a lot of people and a lot of effort. It’s a bit like a car: as soon as you fix one thing, something else breaks.

Nevertheless, lots of people would still like somewhere to share photos (if it was really easy to do), or they might want somewhere to collect stuff they’ve spotted somewhere online, or they might want to keep notes somewhere they can always get to easily, or they might want to share and save conversations with loved ones, or they might want to start podcasting, or they might want to … well, the list goes on.

Posterous allows you to do all this:

• without signing up for anything
• without setting up anything or choosing options
• without having to pay
• without having to wait for more than about a minute for your new blog to be available

How does it work? Send an email to post@posterous.com.

Then what? No, that’s it. That’s all you do. Just send the email. The subject of the email becomes the title of your first post on your new blog and the content of the email becomes the content of your first post.

Wait a short while and an automated email comes back telling you the address of your new blog. Email post@posterous.com again and you’ve got a new post on your blog. Attach a photo to your email and it appears at the top of your post. Attach several photos and you get a control for seeing them all in the order you attached them. Attach a sound file and you get an audio player embedded in your post. Attach a video, or a PDF, or a Word document and … well, you get the picture – it all just works sensibly without you having to do anything complicated.

Some great features

If you want to choose your own subdomain name (like leoville.posterous.com/) you need to sign up, but it’s painless. You can then manage your blog, add additional email addresses if, for example, you want to post from gmail when you’re at home, Outlook when you’re at work, and using your Blackberry mobile email address when you’re out and about.

You can also set up multiple blogs and use them for different purposes. When you have multiple blogs (e.g. a work one, a family one and a club one) you can choose which one you post to by using the subdomain name (e.g. post@yoursubdomain.posterous.com instead of post@posterous.com).

You can allow other people to email to your site by adding them as contributors.

You can make a blog private so that your need to enter a password before you get to see the blog.

If you trust posterous with your login details for other places (e.g. twitter, Facebook, other blogs, etc.) you can post to multiple places at once. You can choose to post to all your other places (by mailing post@yoursubdomain.posterous.com) or you can select just to mail to selected places (e.g. twitter+facebook+posterous@yoursubdomain.posterous.com). You can even use posterous as a way of posting to an existing blog without posting to posterous, which is useful once you realise how convenient posting by email is, but your existing blog doesn’t have that facility.

You can tag your posts just by adding ((tags: your tag)) at the end of your email subject line.

Easy subscription. The people who will find posterous most useful probably don’t use RSS aggregators – even Google Reader. As a result they may not click the Subscribe to this posterous link when they go visit a posterous blog, and if they’ve ever clicked a Subscribe link before they’ve probably been put off the idea because all they’ll usually get is an RSS page with little clue what to do with it. But if they do click the Subscribe to this posterous, and provided they’re signed in, they’re going to like what happens because all that happens is the link changes to tell them they’re now subscribed. What happens after that is that they get a daily email with updates from all of the blogs they’ve subscribed to. And if you’re a regular email user (and who’s not? – for most people it’s still the killer app) then that’s exactly how you want to get things you subscribe to. You don’t want to have to go away and manually check in another place, like Google Reader, you want stuff to come to you, in your inbox.

The bookmarklet. This is just a smart bookmark that you can add to your browser from your posterous site. Whenever you’re using the browser and you come to something interesting, just pull up the bookmark and you can quickly post it to your blog. The bookmarklet window gives you a choice of all the photos on the page and you can choose one of them to include in your post.

A few example uses of posterous

All day diary writing

If you’ve got email on your phone, posterous is a great way of keeping a diary. You never want to write up a diary last thing at night, but you might want to write up little one-liners or short paragraphs during the day when you’ve got a minute, or you’re waiting for the bus and got nothing better to do.

Create a posterous blog and mark it private. Add the email address to your contact list. Then just post to it every now and again.

Share stuff with friends

Out and about and see something interesting, photograph it with your phone and email the picture to posterous. Add your friends as contributors and get them all to email photos. You then end up with a social site for a group of friends that you might not want all your other Facebook friends to see.

Subject-specific site

Want to collect ideas together in one place, either just you or you and friends, family, work colleagues, club members, etc. Make a little posterous site just for one subject. You could have a family site, a site for your department at work, a site dedicated to one specific event – whatever you want, it doesn’t cost anything so it can be as trivial or short-lived as you want. But it can also be a permanent place to gather photos and videos.

Lifestreaming

Because posterous hooks up to Facebook and twitter and FriendFeed and Flickr and YouTube and so on, it means you can post to one place, with a single email, but update all your online locations. Some people follow you on twitter but don’t use Facebook, others are Facebook fanatics but just don’t get twitter. This way one email and you cover everyone.

And if you want you can keep your photos on Flickr, your videos on YouTube, your in-depth thoughts on your WordPress blog and your fly-away, ephemeral comments on twitter – but aggregate them all in one place on posterous to the complete record of you.

Preserving email conversations

Over the years my wife and I have discussed a ton of things via email. Most of it’s inconsequential, but some of it’s funny, sometimes it’s maybe touching, often it’s just plain silly – but almost all of it is now gone. It’d be really nice to have all of that, both sides of the conversations, preserved in one place and easy to search through. With posterous that’s dead easy.

Set up a private blog that only you two have access to. Each change the other’s email address in your contact lists to the email address of this posterous site. Now when you email each other you still get the emails, but the emails are also collected together in one place, online, as a blog.

Podcasting

Want to be a podcaster? Never bothered because it all seemed too complicated. Now it’s not complicated at all. Just record some audio (e.g. on your iPhone) and post it to posterous. Then put the following in your posterous Profile:

<a href="itpc://yoursubdomain.posterous.com/rss">Get the podcast in iTunes</a>

When someone clicks the link it will open up iTunes and subscribe them to your podcast. Alternatively, just putting /rss on the end of your posterous URL to display the RSS feed with enclosed audio files. People without iTunes can use this feed with an alternative podcast client.

Other stuff

I’ve only been looking at posterous for a couple of days. I’m sure there’s lots more you can do with it. Let me know if you know of any other good ideas.

Want to know more? Go to http://posterous.com/faq/.

Suppose you write a diary-style blog and you want to give your great-great-great grandchildren the chance to read about the life of their distance forebears. How are you going to do that? Right now, if you get run over by a bus tomorrow, when your hosting company mails you to tell you you need to renew your hosting deal or your domain name nobody’s going to pay up and your blog will disappear from the blogosphere. It’ll probably remain in some form within the Internet Archive, but no one will find it there and it won’t look or work like it was supposed to.

What you need is for someone (Google is the obvious candidate) to offer to capture your fully functional blog, or website of any kind, and keep it in its fully working state for ever, for a one-off payment.

Probably, for an additional regular payment, they’d snapshot your site on a regular basis. But, because you’ve made the initial lump sum payment, when you pop your clogs and stop paying for the snapshotting, the blog will just stay up there as you left it. I like to think of it as internet cryogenics.

For a company with vast storage capacity and the chutzpah to think they might be in operation for ever, it’s a sure-fire money making venture if ever there was one. So come on Google, what’re you waiting for?

Writer River – the collaborative list of links to tech-writer-related online content – has changed slightly.

You can still post links to it directly, but you can now also syndicate content to the site from your blog. This means that you can produce you own list of things you’ve read and found interesting, publish it on your blog with an accompanying RSS feed, and have those items also appear, alongside everyone else’s, on Writer River.

Why would you want to do this?

There are a few reasons why this might be something you’d like to do.

1. If you maintain a website, you might be interested in getting as many people to visit your site as possible. One way this can happen is through trackbacks (automatically generated links that appear on blog B when a post is published on blog A that includes a link to blog B). If you add items of interest directly into Writer River, the trackbacks will lead back to Writer River. If you list those interesting posts and articles on your own site, the trackbacks will lead people back to your site and boost your numbers.
2. You might just like to have your own list of the things that have interested you, all listed together on your own site. Now, because of the way Writer River is designed, you could already do this by going to the page on Writer River that lists just your posts (you can find this by clicking your name in the list of authors), and grabbing the RSS for this page (e.g. my old list is currently still there at: http://writerriver.com/author/alistair-christie/feed/) and then taking that and publishing it on your own site. RSS stands for Really Simple Syndication and that’s what it’s for: allowing content to be published in one place and syndicated out for publication in lots of other places. However, if you’re a blogger, it seems weird to post items somewhere else in order to get them to appear on your own site. Better to post to your own site and have that content crop up elsewhere (according to whoever wants to pick up your feeds and use them as they were intended to be used).
3. Doing things this way round means that when a Writer River reader, like myself, clicks an item link at Writer River they are transported to your blog, which gives them the context of who it was who found the thing interesting. The down-side to this is that there’s an extra step in there that people won’t be expecting. You’d expect, when you see something that looks interesting and click you click it, to be taken straight there to the original source, but instead you’re taken to the full version of the reference (e.g. a mini post on itauthor.com) and from there you can click through to the original article. This is a bit disorientating and confusing at first, but it does at least reveal something more about the poster, and it clicks up another hit on the poster’s website.

So how do you do this?

The very, very short and sweet version is:

• Produce an RSS feed containing your reading list
• Tell Tom Johnson (the creator/maintainer of Writer River) about the RSS feed. 
  Tom then adds it to the list of feeds that are aggregated into Writer River.

There are a number of ways you could create your RSS feed. The way I’m going to explain uses categories in a WordPress blog. You could equally well use WordPress tags. You could use another type of blog. You could even manually update a hand-crafted RSS file, if you felt so inclined.  

The basic steps for the WordPress method are as follows:

1. Within your WordPress blog, create a new blog category that you’ll give to all your reading list posts. You can call it anything you like (e.g. “What I’m Reading”) – all it’s used for is to collect together mini blog posts that are simply references to something interesting you’ve been reading. You need to be able to separate these out from your other blog posts so that you can display them separately as a reading list.
2. Alter your home page so that these reading list mini posts don’t appear there. They’re going to be listed separately so there’s no point putting them on the Home Page, and if you don’t exclude them you run the risk of alerting subscribers several times about the same reading list entry.  
         
   To exclude a category from your home page, first get the ID number of the category you want to exclude. You can find the category number by going to your Categories list in the WordPress admin pages, clicking the link for a category and looking in your browser’s address bar for the ID number. Make a note of this.
        
   Next, go to Appearance > Editor and open functions.php. Add the following function (changing 34 in this example to the number of the category you want to exclude):
        
   

   function exclude_category($query) {     
       if ( $query->is_home ) {      
           $query->set('cat', '-34');     
       }    
       return $query;     
   }     
   add_filter('pre_get_posts', 'exclude_category');

   (Source: http://blogmum.com/2009/04/how-to-exclude-categories-from-the-home-page-of-your-wordpress-blog/.)

3. Add a couple of posts about things you’ve read recently.
4. Go to the “What I’m Reading” category on your blog (assuming that’s what you called it) and check you’ve got an RSS feed that lists the items you posted. You do this in WordPress by adding /feed to the end of the URL for the category (for example, my feed is http://www.itauthor.com/category/what-i-am-reading/feed).
5. Now, with the web page version of the RSS feed displayed in your browser, right-click the page and choose to view the source code for the page. 
         
   This will show you the XML that produced this page. This is the RSS feed itself and, after a collection of details about the feed itself, it should contain a couple of item elements: one for each item on your list. Each item element should look something like this: 
          
   

   <item>
      <title>Fascinating Blog Post</title>
      <link>http://www.yourblog.com/path/to/this/particular/blog/entry/</link>
      <comments>http://www.yourblog.com/path/to/this/particular/blog/entry’s/#comments</comments>
   
      <pubDate>Sun, 28 Jun 2009 19:31:13 +0000</pubDate>
      <dc:creator>Your Name</dc:creator>
      <category><![CDATA[What I'm Reading]]></category>
   
      <guid isPermaLink="false">http://www.yourblog.com/?p=3926</guid>
      <description><![CDATA[Fascinating Blog Post. This is a fantastic read. You’d be mad not to 
   have a look [...]]]></description>
      <content:encoded><![CDATA[<p><a href="http://www.fascinatingblog.com/path/to/source/article">
   
   Fascinating Blog Post</a>. This is a fantastic read. You’d be mad not to have a look.</p>
   ]]></content:encoded>
      <wfw:commentRss>http://www.yourblog.com/path/to/this/particular/blog/entry’s/feed/</wfw:commentRss>
   
      <slash:comments>0</slash:comments>
   </item>

            
   The bits that get used on Writer River are the title, which is linked to the URL in the link element (i.e. the individual blog post on your blog) and the the contents of the description element (which are an abbreviated, plain text, version of your post). 
        
   The bit you’ll display on your blog are the contents of the content element, which contain the full text of your post, including any links, images, etc.
6. Copy your feed URL (e.g. http://www.itauthor.com/category/what-i-am-reading/feed) and email it to Tom Johnson asking him to add it to the Yahoo Pipes syndication aggregation he’s got set up for Writer River.

Tips

• Make sure the style of your reading list content doesn’t stray too far from the sort of thing that’s already on Writer River. 
• Don’t post too many items. Writer River works best as a “Best Of” site – so stick to posting just the most interesting things you’ve read. Please don’t just post everything you’ve read!

Other things you can do

• Create a feed on Feedburner.
        
  This isn’t necessary, but it adds a useful element of indirection. This might be useful down the line if your feed URL changes because if you promote the Feedburner version of the feed, rather than the original, then you just need to change the URL details at Feedburner and your syndications won’t break.
        
  It also provides a way of gathering statistics about how your feed is used.
• Create a category template for your “What I’m Reading” category.
     
  Again, why would you want to do this. Well if you don’t then your reading list, with it’s mini blog posts, will have to look like all your other categories. However (following Tom Johnson’s lead on this) I wanted to list my reading list without titles. The reason for this is that the title is linked to the individual page and I don’t want people going from the reading list to an individual reading list post: that would be really annoying for readers. What I wanted was that, if someone is interested in an item, they click the link and go to the web page I’m referring to. So, to do this, you need to be able to use a different template to display just this template.
         
  To create a category template, create a PHP file in your theme’s directory called category-n.php where n is the number of your “What I’m Reading” category. As noted above, you find the category number by going to your Categories page, clicking the link for a category and looking in your browser’s address bar for the ID number.
• Make a template that’s used to display single pages where the post belongs to a specific category.
           
  If you’ve got a category-specific template for your reading list you’ll probably want a category-specific single-post template, so that, when someone clicks a link on Writer River and arrives at your site, the post is displayed in a similar manner to the way it looks on the reading list. In my case this means it gets displayed without the title. And (another Tom Johnson tip) you can also put a note at the top of the page to explain that this is one item from a whole reading list of other links, and include a prominent link to that list (i.e. to your “What I’m Reading” category).
          
  To create a single-post template for a specific category, first add the following to your functions.php file, anywhere between the opening and closing PHP tags:
        
  

  add_filter('single_template', create_function('$t', 'foreach( (array) get_the_category() as $cat ) {     
          if ( file_exists(TEMPLATEPATH . "/single-{$cat->term_id}.php") )    
          return TEMPLATEPATH . "/single-{$cat->term_id}.php";     
  }    
  return $t;' ));

  (Source: http://www.nathanrice.net/blog/wordpress-single-post-templates/.)

  Now you can create a post template by creating a PHP file in your theme’s directory called single-n.php where n is the number of your “What I’m Reading” category. For example, the /itauthor.com/wp-content/themes/blueprint directory on my server now contains the templates: category-34.php and single-34.php.
        
  Once you’ve created these template files, you can edit them from the Edit Themes page of your WordPress admin pages. 
  
• Modify the Press This bookmarklet for your blog
        
  The Press This bookmarklet is a browser bookmark with added functionality provided by some nifty JavaScript. It makes it very easy to create a post relating to a web page you’re currently looking at – so it’s perfect for adding items to your reading list. 
         
  
         
  You get a Press This bookmark by going to the Tools page for your WordPress blog and dragging the Press This link into your bookmarks list.
        
  Note: The bookmarklet uses the inbuilt post editor for WordPress, so if you’ve installed a plugin that swaps the normal post editing buttons for something funkier (e.g. I was using Dean's FCKEditor For Wordpress) you’ll have to disable this plugin or you’ll just get a blank text box in the little Press This window. I also had to disable the Disable wpautop plugin, which disables WordPress’s irritating automatic paragraph formatting, because with this enabled any line breaks in the Press This editor disappeared when I published the post.
        
  For me, posting to my reading list is the only thing I use my Press This bookmarklet for, so I want my “What I’m Reading” category to be selected by default.
         
   
        
  
  To add a default category (i.e. already checked) at the top of the Categories list in the Press This window, you need to edit the wp-admin/press-this.php file. Unfortunately you’re going to have to redo this change every time you upgrade WordPress. The stuff you need to add is in red. Change the category number and name as appropriate for your blog.
        
  

  <div id="categorydiv" class="stuffbox">     
    <h2><?php _e('Categories') ?></h2>   
    <div class="inside">     
       
      <div id="categories-all" class="ui-tabs-panel">    
        <ul id="categorychecklist" class="list:category categorychecklist form-no-clear">   
          <!-- Edit this line to suit your setup - my default category number is "34" and its name is "What I'm   
  Reading" –>   
          <li id='category-34'><label class="selectit"><input value="34" type="checkbox" checked    
  name="post_category[]" id="in-category-34"/>What I'm Reading</label></li>     
          <?php wp_category_checklist($post->ID, false, false, $popular_ids) ?>      
        </ul>      
      </div>     

  Kudos to johnke at the WordPress.org forums for suggesting this (http://wordpress.org/support/topic/216525).
• Create a twitterfeed for your reading list.
         
  Twitterfeed is an online resource that allows you to push the contents of an RSS feed (like a feed from a blog) into your twitter account, so that your blog posts (or the first few words plus an abbreviated URL) get sent out to your twitter followers. If you also syndicate your tweets to Facebook it means that your new reading list items will also show up as Facebook status messages.
         
  You can set Twitterfeed to check the RSS feed for your reading list once an hour. You can use the Advanced settings to add a prefix to these posts (I use “I've been reading: “), and I’d recommend setting it to include the “title only” rather than “title & description” because once you’ve added the prefix and the link to your post there isn’t much room for any more than two or three words from your post content.
         
   

Respect

I’ve already mentioned him a few times and, at the risk of embarrassing him, I must doff my cap once again to Tom Johnson who created Writer River and came up with most of the ideas I’ve fleshed out in this post.

Want to find out more? Go read these posts on Tom’s blog:

• "What I'm Reading": A New Feature on My Site and a Tweak of Writer River
• I Need Your Human Aggregated Content

Create a twitterfeed for your reading list.
       
Twitterfeed is an online resource that allows you to push the contents of an RSS feed (like a feed from a blog) into your twitter account, so that your blog posts (or the first few words plus an abbreviated URL) get sent out to your twitter followers. If you also syndicate your tweets to Facebook it means that your new reading list items will also show up as Facebook status messages.
       
You can set Twitterfeed to check the RSS feed for your reading list once an hour. You can use the Advanced settings to add a prefix to these posts (I use “I've been reading: “), and I’d recommend setting it to include the “title only” rather than “title & description” because once you’ve added the prefix and the link to your post there isn’t much room for any more than two or three words from your post content.
       
 

Respect

I’ve already mentioned him a few times and, at the risk of embarrassing him, I must doff my cap once again to Tom Johnson who created Writer River and came up with most of the ideas I’ve fleshed out in this post.

Want to find out more? Go read these posts on Tom’s blog:

• "What I'm Reading": A New Feature on My Site and a Tweak of Writer River
• I Need Your Human Aggregated Content

Answer: download and install the free, open source alternative to Illustrator:
 
http://www.inkscape.org/download/

Inkscape allows you to import Illustrator-format .ai files. You can then edit the diagram in Inkscape and output a new .png or .emf for the manual.

The only problems I found doing this were:

1. Text entered in Illustrator will typically have some automatic kerning added to make it look just right. Inkscape can’t handle kerning and you won’t be able to edit the text until you remove it. So you need to select the text you want to edit and choose Text > Remove Manual Kerns.
2. Inkscape add lots of object groups. Things are grouped within other things within other groups within other groups … So, to move individual objects around you need to click on the thing you want to move (which will usually select everything in the diagram) and keep pressing Ctrl + Shift + G until enough of the groups are ungrouped and you can see a dotted selection box around the object you want to move.

I really like Inkscape. It does most of the things you can do in Illustrator – in a slightly clunky way perhaps, but it’s a powerful tool and will allow you to produce professional-looking diagrams.

If you just want to create diagrams from scratch and you don’t need to edit existing Illustrator diagrams, you might prefer to try out a true Web 2.0 solution instead: Raven – one of the suite of image tools from Aviary.

Raven is a free online vector design tool that works completely within the browser. It’s got a very good-looking interface and I found its Bezier curve editing much easier to use than the same thing in Inkscape. But, because some of the functionality is happening on the server side, you have to put up with a little delay uploading and downloading files to and from the server if you’re going to be creating and maintaining them in Raven. For a browser app, though, it’s a pretty amazing piece of coding and design work.

I only create simple diagrams, but if you’re a bit of an artist you should have a look at this video to see what you can do in Raven:

And if you’re looking for a free alternative to Photoshop or SnagIt, check out what else Aviary does in the browser:

Most of the time this means listening to podcasts and usually these days, where audio is available on a Web page it’s in MP3 format and it’s also available as a podcast. But in some places audio is still only available as RealAudio, which has to be played on your computer using RealPlayer.

So, if you’re like me, you need a way of getting audio that’s only available in RealAudio format off a Web page, into MP3 format, and into your iPod or other MP3 player.

My particular case was that I wanted to listen to the well-known audio documentary “Ghetto Life 101”. This is available from Sound Portraits (http://soundportraits.org/on-air/ghetto_life_101/) as a RAM file. Alternatively you can find a collection of David Isay documentaries, all as RAM files, here: http://www.talkinghistory.org/isay.html.

So here’s one way of doing this (this relies on using Firefox as your browser):

1. Download and install Firefox if you don’t already use this as your browser.
2. Once you’ve installed Firefox, download and install the DownloadThemAll Firefox add-on.
3. Browse to the Web page containing the RAM file you want to play on your MP3 player. For example, try going to http://www.talkinghistory.org/isay.html.
4. Choose Tools > DownloadThemAll! Tools > DownloadThemAll!
   
   The DownloadThemAll! dialog box opens, listing all the downloadable files on the Web page.
5. Unselect any selected Filter checkbox and enter *ram in the Fast filtering field. This will select just files with the .ram file name extension.
   
   In this screenshot I’ve used the filter *isdn*ram, because the page I’m processing has three versions of each RAM file and I only want the ISDN-quality files (which all have “isdn” in the file name)
   
   
6. In the Save files in field, enter the location where you want to save the file(s).
7. Click Start!
8. Download and install FormatFactory.
9. Start FormatFactory and click All to MP3.
   
   
10. Click Add File.
11. Select all the RAM files you downloaded.
12. Click OK.
    
     
13. Copy the resulting MP3 files to your MP3 player, or drag them into your music folder in iTunes and sync your iPod.

If you’re downloading a lot of files, you might like to give them all the same artist or album tag. To do this really easily, right-click this link and download and install ID3-TagIT (note: this link points to a zip file containing an .exe file – always run your virus scanner on any executable file you download before running it).

Matthew Ellison runs his own UK-based training and consulting company, specializing in user assistance design and technology. He coordinates the annual UA Europe Conference and is himself a popular speaker at conferences and training events around the world. He also regularly publishes articles and reviews on user assistance.

In this edition of the ITauthor Podcast I talk to Matthew about the UA Europe Conference.

 
We discuss:

• the number of countries from which delegates attend the conference
• what it’s like being the organiser of a large conference for technical communicators
• how can delegates justify the budget to attend the UA conference in these difficult economic times
• the sessions and speakers we can look forward to at this year's conference
• the No.1 issue affecting technical writers today
• trends or changes technical writers ought to be aware of
• what keeps Matthew busy when he’s not organising and running the UA Europe Conference

Talking about the “good enough” philosophy for user assistance, Matthew says:

"There's a fine line between doing documentation that's good enough and not being professional, and I certainly would never want to put something in front of a user that I didn't consider a professional piece of work."

Find out all about the UA Europe Conference at: http://www.uaconference.eu.

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

This time round – recorded over Skype – Graham and I discuss:

• “technical author”, “technical writer” or “technical communicator”
• being forced out of technical writing by personal economics
• why contractors are more productive than permanent documentation staff
• an occasion where the tech writer was the closest thing to a Subject Matter Expert in an application development team
• tech writers being considered “the lowest of the low”
• why management find tech writers the easiest people to “let go”
• using voiceovers rather than written callouts in videos
• is documentation sometimes really remedial work on a bad user interface?
• what do we actually need to document in an online help system?
• being proud of the work we do

StoryCorps recording in this podcast

This episode of the podcast ends with a StoryCorps recording of Ed Miller talking to his son EJ. This audio was provided courtesy of StoryCorps. Please visit www.storycorps.org for more details and, if you like what they do, please consider making a donation to help keep the StoryCorps mobile units on the road.

The part of this recording that I really identified with was where he says:

We go to the mall nowadays, me and Mom, and I see dads walking with their sons or daughters, holding their hands, and I tell you, my heart aches for the days when I used to do that …

Podcast recommendations:

The Writing Show  –  http://www.writingshow.com/index.html 
(Graham refers to the recording I made for the Writing Show.)

 
The StoryCorps Podcast – http://www.storycorps.org/listen/podcast

Application recommendations:

 
Skype – http://www.skype.com

 
Techsmith Snagit – http://www.techsmith.com/screen-capture.asp 

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

This time round – recorded over Skype – Graham and I discuss:

• Migrating online help projects from RoboHelp to Madcap Flare
• How I use twitter and why Graham doesn’t
• Integration of social media – for example, information flowing from your blog to twitter to Facebook
• The death of blogging?
• Hard times for ITauthor’s stats
• Geoff Pullum, Geno Washington and the Ram Jam Band 

This is the photo I mentioned of Geoff Pullum (who was calling himself Jeff Wright – bottom left) with Geno Washington and other members of the Ram Jam Band.

I hadn’t realised, until scouting around the internet to find this picture, that Geno Washington and The Ram Jam Band had two of the biggest selling UK albums of the sixties. Hand Clappin, Foot Stompin, Funky Butt Live was in the album charts for 48 weeks during 1966 and was only out-sold by The Sound of Music and Bridge over Troubled Water.

Podcast recommendations:

 
Adam and Joe – http://www.bbc.co.uk/podcasts/series/adamandjoe/

 
Great Lives – http://www.bbc.co.uk/podcasts/series/greatlives/

 
Application recommendations:

WebEx iPhone application – http://www.webex.com/iphone/

 
Freemind – http://freemind.sourceforge.net/wiki/index.php/Main_Page 

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

If you publish content on the internet, for the world to view, you might wonder how your site performs around the world. Pages might load okay for you, but how quickly do those same pages load for people on other continents?

A handy tool for checking on this is the InternetSupervision Web site:

http://internetsupervision.com/scripts/urlcheck/check.aspx

You stick in a URL and click Check and it loads those pages on servers around the world (so they say) and reports back its findings. Each time you click Check the numbers change, presumably because the servers are busy doing other stuff, and the connections they’re using each get quicker and slower from second to second. But it gives you an indication of who’s getting the best of your Web site and which locations probably have to wait longer for pages to finish loading.

Here are the stats for www.itauthor.com:

The BBC Home Page, by comparison, generally takes about 0.1 of a second to load in the UK, and is a bit faster than the current ITauthor Home Page in most place, but is about the same on their Los Angeles server.

Professor Geoffrey Pullum, Professor of Linguistics at University of Edinburgh, recently wrote an article called ‘50 Years of Stupid Grammar Advice’ in the Chronicle of Higher Education on the 50th anniversary of the publication of Strunk and White’s Element of Style.

I visited Professor Pullum in his office in a beautiful new university building in the heart of Edinburgh to talk to him about his article and to discuss grammar and technical writing.

Among other things, we talk about:

• the split infinitive
• “none of us are” or “none of us is”?
• that and which
• the view of grammar as commandments brought down from the Grammar Mountain
• the pressure to enforce grammar rules, even when you don’t believe them
• why do most of us know so little about grammar?
• if we shouldn’t use Strunk & White, where should we go for grammar advice?
• nerdview

We also mentioned Professor Pullum’s talk at last year’s UA Conference Europe:
The Piranha Brothers, the Unwritten Grammatical Law, and the Phenomenon of Nerdview,
which is well worth reading if you find this interview interesting.

Related recordings:

• Professor Pullum on NPR’s Talk of the Nation phone-in, April 16, 2009
• Professor Pullum interviewed on NPR's Here and Now show from September 2006
• Marc Acito marks to 50th anniversary of Strunk & White’s Elements of Style on NPR, April 2006

Related blog posts:

• Happy Birthday, Strunk and White! – from the New York Times’ Room for Debate blog
• Pullum on Strunk and White from Orange Crate Art
• Hardly [adverb] convincing [adjective] from Orange Crate Art
• The End of Strunk from SLOG

Other links:

• Geoff Pullum’s Home Page
• Language Log

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