I’m posting this here just because I spent far too long looking for the answer to this problem, before eventually finding a solution at

So all of the following comes from:
http://stackoverflow.com/questions/3480074/how-do-i-convert-unicode-codepoints-to-hexadecimal-html-entities and is thanks to Stackoverflow users Joey and Artefacto.

The problem

In short:

Data that I want to display on a Web page contains escaped Unicode code units in it (like \u0096) that I want to convert into HTML entities (like –) so that they will show up correctly on the Web page.

In a little more detail:

I have a Web page with a table control that uses JSON. I have a PHP script that takes some user input (search query terms), goes and searches a database, forms the search results into an array (called $data) with the correct format to pass to json_encode():

$str = json_encode($data);

However, the value you pass to json_encode() must be UTF-8 encoded data, and mine isn’t, so I need to pass it through utf8_encode() first, before I pass it to json_encode(). For example, for the contents of the name field:

utf8_encode($matchedRecord['name'])

The result of this is that any slightly unusual characters, like the en dash (–), come back transformed into one or more escaped Unicode code units (e.g. the en dash becomes \u0096). When this is included in an HTML page and sent to a browser it’s displayed as a strange little symbol by Firefox (e.g. ), or just not displayed at all by Internet Explorer.

So I need to take the string from json_encode() and pass it through something that will convert the escaped Unicode code units (like \u0096) into HTML entities (like –) so that they will show up correctly in the browser.

The solution

$str = preg_replace('/\\\\U0*([0-9a-fA-F]{1,5})/i', '&#x\1;', $str);

This did the trick for me. However, Artefacto supplies a function that handles UTF-16 code points (i.e. characters made up of one or two 16-bit code units):

$str = unenc_utf16_code_units($str);
   
function unenc_utf16_code_units($string) {
    /* go for possible surrogate pairs first */
    $string = preg_replace_callback(
        '/\\\\U(D[89ab][0-9a-f]{2})\\\\U(D[c-f][0-9a-f]{2})/i',
        function ($matches) {
            $hi_surr = hexdec($matches[1]);
            $lo_surr = hexdec($matches[2]);
            $scalar = (0x10000 + (($hi_surr & 0x3FF) << 10) |
                ($lo_surr & 0x3FF));
            return "&#x" . dechex($scalar) . ";";
        }, $string);
    /* now the rest */
    $string = preg_replace_callback('/\\\\U([0-9a-f]{4})/i',
        function ($matches) {
            //just to remove leading zeros
            return "&#x" . dechex(hexdec($matches[1])) . ";";
        }, $string);
    return $string;
}   

I’ve been listening to the audiobook of Walter Isaacson’s new biography of Steve Jobs. Jobs’ desire (bordering on compulsion) to produce the very highest quality products warms my heart. Admittedly, he sounds like he was an incredibly difficult person to be around a lot of the time, and you’d have needed to be able to adopt a water-off-a-duck’s back approach to a lot of his outbursts, but I admire the fact that he allowed his intuition to tell him when something wasn’t right and he just wasn’t prepared to settle for second best.

Take the following quote:

At the West Coast Computer Faire in April 1981 … Adam Osborne released the first truly portable personal computer. It was not great – it had a five-inch screen and not much memory – but it worked well enough. As Osborne famously declared, "Adequacy is sufficient. All else is superfluous." Jobs found that approach to be morally appalling …

Like Jobs, I find the “adequacy is sufficient” attitude appalling (though I’m not sure about morally appalling). It reminds me of the tenet of the Agile development methodology that you should aim to deliver goods and services that are “just barely good enough”. If a product is good enough to ship and be accepted by the customer then it’s good enough, and any effort expended on trying to make it better than that, in your opinion, is simply an opportunity cost – that is, you could have spent that time profitably on other paid work.

Colin Chapman, the founder of Lotus Cars, claimed that the perfect racing car would fall to pieces as soon as it crossed the finish line to win a race. If it didn’t it just showed that it was over engineered. Of course this was hyperbole. Chapman was exaggerating to make a point. You only need to look at those beautiful Lotus racing cars he designed to realise that they were engineered for more than merely crossing the finishing line first.

I became a convert to the Agile methodology a few years back and I still believe it’s got a lot to offer. For a while I tried to convince myself that aiming to deliver “barely good enough” was the way to go, but it always rankled with me. These days I find the idea repugnant. To me it represents one of the worst aspects of the business world: the short-termist approach of “let’s just ship whatever we can manage to persuade the customer to accept and involves the least possible work for us”. It’s an accountant’s balance sheet view of product management: the smallest possible number in red that gives the biggest possible number in blue – maximise the credits, minimise the debits, and ship whatever whatever we can get away with. This kind of thinking will get you sales but it will not get you repeat business and it’s not a recipe for success (by which I mean growing numbers of happy customers and happy staff).

Steve Jobs had the signatures of the Macintosh team moulded on the inside of the cases of the original Apple Macs. That’s right: the inside – and you couldn’t even open the case to see this. Why did he do this? Well imagine how you’d feel if yours was one of those names! For all the berating and bawling out he did, imagine the team-bonding, morale-boosting effect of having your name moulded into the first Apple Mac. Wouldn’t you want to produce the best computer in the world if you knew your signature was on it. (If the answer to that question is no then you would never have been employed as part of that team.)

Jobs also fretted over the exact colour of the case, insisted on rounded corners for dialog boxes, obsessed over the choice of system fonts – things that the majority of buyers wouldn’t consciously even notice and wouldn’t really care about even if their attention was drawn to it. But Jobs noticed, and he cared about these things and he wanted to produce a product that he could be genuinely proud of. To an extent he was doing it for himself. He was designing the computer he wanted to own. And he continued doing this with hardware products (Apple software is another story altogether) for the rest of his life.

The point is that I increasingly feel, for our own self-respect and self-regard, we should always try to do the very best work we are capable of. Adopting the “adequacy is sufficient” attitude, or believing that “just barely good enough” should be the height of your aspirations, inevitably leads to a feeling that all you need to do is the minimum you need to do to avoid getting the sack so that you can continue collecting your pay cheque. The accountancy ethos rubs off: minimum personal outlay for maximum financial income.

For me that’s not enough. Just barely good enough is never going to be enough. It’s laziness. It’s a lazy, unambitious, unimaginative outlook on life that I want no part of – and I don’t want to have to work with people who think that way either. I want to aim to do work that is every bit as good as I can make it – whether or not anybody else ever notices. Personally, a good day for me is when I end the day feeling like I’ve done something I can be proud of.

None of what I’m saying is new or original. People have been complaining loud and long about Facebook’s user interface – not least because the folks in Palo Alto keep changing it, without warning and often for no apparent reason. And yet, despite all the changes, the usability doesn’t seem to get any better. Things that were in one place are now hidden away somewhere else. A feature that was called one thing last time you looked for it is now called something completely different. It’s insane!

What’s made me ponder this today is that I’ve just spent over an hour figuring out how to stop Facebook importing my blog entries as Notes – something I must have turned on at some time in the past but then forgot about and today, when I realised this was happening, decided to turn off. Easier said than done though! Go look for how to do this in the sparse Facebook Help. Nothing! Of course I then fell back on Google, however the endless changes to the user interface mean that none of the pages I found had instructions or screenshots that matched the current layout or how things currently work.

Now I realise I’m pissing into the wind complaining about this. As of today Facebook has around 800 million active users and revenue of over $4 billion. 800 million people can’t be wrong – right? I just find it a little depressing that so many people are prepared to put up with something so poorly designed. And Facebook is not an isolated case of a successful software product with God-awful usability. Every time I use the iTunes application it baffles me that Steve Jobs, who was such a master of usability and beautiful design when it came to hardware, could allow the Apple brand to be associated with such a rank pile of crap as iTunes.

How to stop Facebook importing your blog entries as Notes

So, just in case anyone else is struggling over this like I was today (although I realise the shelf-life of the following documentation will be extremely brief), here’s how you turn off the automatic importing of an RSS feed into your Facebook account.

1. Log in to Facebook.

2. Click Notes in the left column.

   

3. Click My Notes to view just your own added or imported notes.

4. At the bottom of one of the imported notes, click View full note.

   

5. Click Edit import settings in the left column.

   

   Important: You only see this option after you’ve displayed the full view of one of your imported notes. This was the elusive bit of information that resulted in me wasting over an hour on doing something that should have taken a couple of minutes.

6. On the Import a blog page, click Stop Importing.

   

• Is not in your DNS system so you can’t get to it using a host name
• Has a static IP address that’s assigned on the machine itself - but you don’t know what the address is

The answer is you need to use trial and error to find and IP address that asks you for a user name and password and when you plug in the user name and password you know are valid you get a connection.

This is a whole lot quicker if the machine accepts ping requests (which are basically little “hello, anyone there?” messages fired at a computer, to which the machine answers “yup,” if it wants to, and your computer tells you how long it took to get a response).

If you don’t already have a network scanner* installed, here’s a little shell script you can run from a Windows command prompt. Fire up the command console (cmd.exe) and enter this (changing the bits in red to suit yourself):

SET fl=c:\Alistair\ipaddresses.txt & ECHO =================================================== >> %fl% & ECHO.%date% %time% >> %fl% & FOR /L %i IN (0,1,255) DO ping -n 1 192.168.0.%i | FIND /i "Reply" | FIND /i /v "unreachable" >> %fl%

In the above:

• c:\Alistair\ipaddresses.txt is the path to the log file where I want to write the IP addresses
• (0,1,255) means set the variable %i to 0 to start with, increment by 1 each time the FOR loop loops and stop after it reaches 255
• 192.168.0.%i is the IP address range (in this case this starts at 192.168.0.0 and ends at 192.168.0.255)

The first FIND command finds all lines of output containing “Reply.” These get passed to the second FIND command which removes any lines that contain “unreachable.” The result is that ping output is only logged where the ping to an IP address was responded to.

The output in the log file looks something like this:

===================================================
28/08/2011  9:22:24.26
Reply from 192.168.0.1: bytes=32 time=24ms TTL=64
Reply from 192.168.0.41: bytes=32 time=82ms TTL=64
Reply from 192.168.0.42: bytes=32 time<1ms TTL=128

A variation on the script is to look for host names for the IP addresses and log these, if found. This takes much longer to run but could be useful if you need to find out what machines on your network can be pinged with their host name:

SET fl=c:\Alistair\ipaddresses.txt & ECHO =================================================== >> %fl% & ECHO.%date% %time% >> %fl% & FOR /L %i IN (0,1,255) DO ping -a -n 1 192.168.0.%i | FINDSTR /i "Pinging.*\[ Reply" | FIND /i /v "unreachable" >> %fl%

Which produces output like this:

===================================================
28/08/2011  9:22:24.26
Reply from 192.168.0.1: bytes=32 time=24ms TTL=64
Reply from 192.168.0.41: bytes=32 time=82ms TTL=64
Pinging rolumus [192.168.0.42] with 32 bytes of data:
Reply from 192.168.0.42: bytes=32 time<1ms TTL=128

In this example, just one of the machines could be reached by a host name: romulus.

Turn it into a batch file

If, for some reason, you can see yourself needing to use this script now and again you might want to save it as a batch file that you can run simply by double-clicking the file in Windows Explorer. Here’s an example of a batch file that runs the second (slower) of the scripts:

@ECHO OFF
REM Created by Alistair 28/8/2011
REM See blog post on this: http://www.itauthor.com/2011/08/28/scan-for-available-ip-addresses/
REM For more batch file commands, see: http://ss64.com/nt/
SET fl=c:\Alistair\ipaddresses.txt
ECHO Scan IP addresses for ones that accept a ping request.
ECHO The output from this batch file is logged in %fl%
ECHO Scanning ...
ECHO =================================================== >> %fl% & ECHO.%date% %time% >> %fl% & FOR /L %%i IN (0,1,255) DO ping -a -n 1 192.168.0.%%i | FINDSTR /i "Pinging.*\[ Reply" | FIND /i /v "unreachable" >> %fl% & ECHO 192.168.0.%%i
ECHO Scan completed. See log file (%fl%) for results.

Just save this as a file with a .bat file name extension (e.g. checkIPaddresses.bat) in a location that doesn’t require Administrator privileges. For example, if you want to run it from your desktop don’t save the batch file to your desktop, save it somewhere like C:\YourStuff\batchFiles\, then create a shortcut and put the shortcut on your desktop.

Network scanners

Be very careful if you’re considering installing a network scanner. There are a lot of port and IP addresses scanners out there and a lot of them are malware. They might do the job OK but they also come with viruses, so watch out. There are infected/corrupted versions of reputable scanners, so don’t assume something is OK just because you’ve read good stuff about it, unless you are completely confident you’re getting the kosher version of it.

More information

A good source of information about Windows shell commands is: http://ss64.com/nt/

Test first

Chapter 3 of Michael Hartl’s Rails Tutorial introduces you to testing within Rails development. I’ve known about test-driven development (TDD) for a long time, but I’ve never actually done it. So I was looking forward to finding out how you write tests for something you’ve not built yet.

To be honest, not only have I never written tests before writing the code, I’ve never written tests full stop. In all my years of writing software programs (I wrote my first program, in BASIC, in 1989, then worked my way through C, Visual Basic for Applications, JavaScript, Perl and PHP) I’ve never actually written a test in software to test software I’ve written. So, this feels like a step up from my hacky habits towards a modicum of semi-professional rigour.

RSpec

RSpec (the R is for Ruby, Spec for Specification) is a Ruby package that lets you use a simple grammar to create specifications for software you intend to build. You can then test the software against the specification. The process goes something like this:

The above is from Behavior-driven testing with RSpec by Bruce Tate, which is a good tutorial on RSpec if you want to stray from Michael Hartl’s tutorial for a while.

Fixing the ANSICON warning

When I ran the RSpec tests for the first time (section 3.2.2 of the Rails Tutorial):

$ bundle exec rspec spec/

it worked but the output text included the message:

 *** WARNING: You must use ANSICON 1.31 or higher (http://adoxa.110mb.com/ansicon) to get coloured
 output on Windows

This sounds serious but it only means your console (in my case MINGW32 running bash – which came when I installed git from GitHub) isn’t displaying the colours it could be displaying.

If you want to fix this:

1. Go to http://adoxa.110mb.com/ansicon/ and download ANSICON 1.40.
2. Unzip the downloaded zip file.
3. Open a command console as Administrator (i.e. type cmd into the start menu, right-click cmd.exe and choose Run as Administrator).
4. cd to the location of the unzipped files
5. You’ll find subdirectories called x86 and x64. On a 32-bit machine go into the x86 directory. On a 64-bit machine go into the x64 directory.

6. If you want to see command syntax enter:

   ansicon.exe -h

7. To install ANSICON, enter:

   ansicon.exe -i

Autotest and Growl

The tutorial describes using Autotest and Growl to run tests and notify you when your test completes by displaying a summary of the test results. The good thing about using Growl is that, you can kick off a suite of tests and then go away and do other things in Windows while the tests run. When they finish, a message is displayed on top of all other windows.

I’m still pretty hazy about exactly what Autotest does and doesn’t do. As its name suggests it obviously runs tests automatically, but I’ve yet to figure out why tests get triggered when you save changes to some files but not others. However, it’s very handy for something to be sitting waiting for you to change certain files and, when you do, checking the file to make sure you haven’t contravened any of the definitions in your specification. You do this by opening a dedicated console window, entering:

$ autotest

and then just leaving the window open in the background so that the autotest process keeps running and will run your tests as you work on your Rails project.

I set up Growl by following Michael Hartl’s instructions (plus the instructions he cross-refers to for Windows users):

$ gem install autotest -v 4.4.6 $ gem install autotest-rails-pure -v 4.1.2 $ gem install autotest-standalone $ gem install autotest-growl

Download and install Growl for Windows from:

http://www.growlforwindows.com/gfw/ 

Create a .autotest file as follows:

$ gvim ~/.autotest

Containing the single line of text:

require 'autotest/growl'

Of course if you want to use Growl to notify you the results of tests you’ve got to start it first. In Windows 7 just enter growl in the Start menu search box and then press Enter when Windows finds the Growl program. I suppose if you were working on Ruby all the time and regularly running tests you could set up Growl to start automatically when Windows starts.

When you start Growl it displays a message telling you it’s running, but that’s all it does. It’s just waiting for a notification to display. Growl lives in the system tray. You can click it and change the setup options:

I’m not entirely sure what added Autotest to the list of applications. It wasn’t there at first but one of the command-line commands must have added it.

After setting up Growl when you start Autotest:

$ autotest

and your tests complete you get a sound and a visual notification telling you whether your tests passes or failed. I chose the notification style called Visor which slides down from the top of the screen:

No DRb server is running

If, when you run autotest (or when you just run bin/rspec spec), you get:

No DRb server is running. Running in local process instead ...

it means Spork isn’t running.

Spork is a gem that you put into the Gemfile for your project. It contains a Distributed Ruby (DRb) server that enables Ruby programs to work with other Ruby programs by sending/receiving messages via the DRb server. So one Ruby program can use a method that’s defined in another Ruby program running on the same computer, or on a computer somewhere else on the network.

More about Distrubuted Ruby here: http://ruby.about.com/od/advancedruby/a/drb.htm

You need to associate your Ruby program with Spork. The setup instructions for Spork are described in the tutorial here: http://ruby.railstutorial.org/chapters/static-pages#sec:spork

To start Spork, open a new console window for the purpose, navigate to your project directory and enter:

$ bundle exec spork

You can then go back to your other console window and run autotest and it should complete the tests in less time, because it’s not having to load so much stuff (Spork has preloaded that stuff and is sitting waiting for connections).

Switching Web server from WEBrick to thin

Rails comes with the lightweight WEBrick Web server that you can use for testing pages – as described in the Rails Tutorial. However, I had a few odd little niggles with it, and it seemed very slow, so I switched to using an alternative called “thin”. To do this you need to install the eventmachine and thin gems.

Note: You need a particular version of eventmachine for thin on Windows.

1. At the command line, change directories to your project directory.

2. Edit the Gemfile file within the project directory to:

   group :development do   …   gem 'eventmachine', '1.0.0.beta.2'   gem 'thin' end

3. Then run:

   $ bundle install

4. You can then start the server like this:

   $ rails s thin

   Or, to redirect it’s output to a file and detach the process from the bash shell:

   $ rails s thin >> thin_output_log.txt &

Solving the ssh.exe problem

After initially using GitHub without any problems, when I tried to update GitHub a few days later I discovered that this was no longer working.

Whenever I tried to do anything involving a connection to GitHub – even just ssh git@github.com – I got a message saying: ssh.exe has stopped working.

After much fruitless Googling, uninstalling and reinstalling Git for Windows, disabling anti-virus, etc. I finally discovered the fix, which is to set the file properties of ssh.exe and ssh-keygen.exe (in the Git/bin directory) so that they run in either Windows XP or Vista compatibility mode (either will do).

I presume this is because I’m running 64-bit Windows 7. But I’ve no idea why it worked fine when I installed it initially.

Bizarrely, after restarting Windows I seem to have to go through this process again, even though the settings indicate that it should run in compatibility mode. It appears to be necessary to go to this tab in the Properties dialog box for these files and click OK to force this mode to be used.

Answer: If you take screenshots of windows with the Windows Aero theme (i.e. semi-transparent window chrome) then it’s a good idea to always use a plain white background to avoid the distraction of other text or bits of underlying windows showing through.

To quickly display a white screen:

1. Copy and paste the following into the address bar of your browser:

   javascript:document.write(), document.close(); void 0;

2. Press Enter.

3. Press F11 to get rid of the browser chrome (and F11 again to get out of full-screen mode).

Bookmark it

For a quick blank screen at any time (without having to remember the Javascript), save it as a bookmark by either right-clicking the following link and choosing Bookmark This Link (in Firefox) or Add to Favorites (IE), or – if you’re using Chrome or Safari – display the Bookmarks Bar and drag the following link into it:

Blank Page

Alternative solution: Save a blank page

Alternatively, you can make a blank web page and save it to your desktop (or anywhere else) for quick access whenever you need a white background:

1. Create a text file containing the following:

   <html><body></body></html>

2. Save this to your desktop (or wherever) with an HTML file name extension – e.g. WhiteScreen.html.

Now you can double-click the file to display a white web page. Again, press F11 for full-screen mode. You can bookmark the page if you prefer using this method rather than the Javascript method.

I have a load of files with date/time-based file names in the format dd_mm_yyyy hh_mm.wav. I’d prefer these files to have a format that allowed them to be sorted in a directory in a meaningful way by the file name (i.e. yyyy-dd-mm). I also have a pet hate of file names containing spaces. It would also be useful to show the day of the week in the file name. So what I’d really like is a file name in the format yyyy-dd-mm_hhmm_<dayname>.wav.

In the past I’d have written a Perl script to rename a batch of files, but since I’ve been looking at Ruby recently it made sense to have a bash at doing this in Ruby.

Here’s the program I came up with:

Anyone looking at this who knows how to code in Ruby will, doubtless, immediately see all sorts of issues with it. But I’m quite happy with it because it didn’t take long to write and it does the job.

I’ve saved this file as RenameWavFiles.rb in the iTunes directory where all these files get created and I have a shortcut to that directory so that all I need to do is click the shortcut icon to open the directory in Windows Explorer, then double-click the Ruby file to rename any new files. The files are copied to a subdirectory with their original names just in case there’s a problem. Job done!

I wrote the code in Vim 7.2 and one nice thing about the GVim incarnation of Vim is that, in the Syntax menu, there’s a Convert to HTML option that creates the output you can see above.

Introduction

I have a stinking cold this weekend and, apart from dragging myself out to walk the dog, I’ve been fit for nothing else but sitting on the sofa (or lying in bed) with my laptop. But I thought I’d try to use the time profitably by finally getting around to learning how to use Rails. I’ve been meaning to do this for over five years now – i.e. since the days when all the tech podcasts I listened to hyped it up as the great new thing on the Web.

Back in 2006 I even bought my daughter a copy of the original edition of Chris Pine’s Learn to Program book – which uses Ruby to teach programming – on the off-chance that she might get interested in coding. We sat and went through some of it together but she really wasn’t interested so the book then lay unread for years, until a couple of months back when I packed it into one of several big cardboard boxes with all my other computer books and it went off to the Oxfam bookshop.

The trouble has been (apart from inertia, laziness and wariness about potentially wasting lots of time on yet one more thing I really don’t need to know about) that I’ve been doing most of the dynamic Web page goodness I need to do quite fine all these years using PHP (well, a combination of PHP, MySQL, Javascript, CSS and plain old HTML to be precise). So I haven’t had a need to learn about Rails. But PHP seems antiquated these days and I really feel like I need to move on. I also wanted to get a better understanding what Model-View-Controller (MVC) is all about. I understand the principals of MVC, but it’s not until you actually use a programming concept that you really understand it.

Before PHP I was a committed Perl devotee and it took me a while to switch to PHP because I really liked Perl and I was doing some fairly complex stuff with it. I got into Perl because I’d started writing Web pages in HTML, discovered you couldn’t do much with HMTL alone, started writing Javascript, discovered that that had its limitations (as well as being the source of a great deal of pain back then) and so I ended up, like many people who followed the same route, writing Perl CGI scripts. That was before PHP had really got going and, for hobbyist Web site creators like myself, Perl CGI scripts on Apache servers was about the only way to go. And I really enjoyed writing Perl. The only thing that did for Perl was the whole issue with modules: figuring out which modules you needed, which versions were installed, installing multiple versions of modules so as not to break someone else’s scripts, and so on. Modules were a bit of a nightmare. PHP just seemed to have everything built in and you could just crack on and do the coding.

So I switched from Perl to PHP and never looked back. But I do remember being horrified at first by the mix of HTML and code within PHP files. The recipe seemed to be: chuck all your ingredients (design, content, functionality) into one bowl and give it a good old mix. It struck me as having massive potential for confusion and maintenance issues. With my Perl scripts I’d used separate HTML templates. The Perl script requested by the browser called up other scripts as required, did the processing, worked with the database, gathered together all the dynamic content and then selected from a choice of templates and built the final HTML by replacing placeholders with the dynamic content. I really liked the idea of keeping the page design and static content as separate as possible from the code – it just seemed a lot cleaner that way. So that’s one thing I’m expecting Rails to have got right and I’m looking forward to getting back to that kind of way of doing things. We’ll see.

Starting point

I can’t code in Ruby. I’ve read up about it at various points during the past few years and I’ve written a few little Ruby programs in the course of dipping my toes in the subject. Specifically, I’ve spent some time with these resources:

• Chris Pine’s book, mentioned above (I recently downloaded the 2nd edition to my iPad)
• Beginning Ruby: From Novice to Professional by Peter Cooper
• http://tryruby.org/ – a great, try-it-online-as-you-go, getting started tutorial
• why's (poignant) Guide to Ruby – better experienced than described; the story behind this is as intriguing as the book itself

But, as of today, I have to say I really can’t code in Ruby. Should I have concentrated on this for a bit before jumping into Rails? I’ve read conflicting advice answering this question definitely yes, and no, it’s not necessary. It’ll be interesting to see how much this lack of knowledge holds me back or trips me up.

As far as Rails goes, before this weekend I’d watched pretty much every video I could find about Rails at one time or another – including all the ones where someone zips through and creates a (seemingly) fully functioning social media Web site in about ten minutes. For non-macho programmers like myself that kind of thing (where someone is talking super fast and typing commands even faster, and things are zapping past you on the screen: zap, there goes validation, blink and you miss it, there goes authentication …), that just puts me off, because what it says to me is: only ubergeeks will really find this as easy as this guy seems to – the rest of us would doubtlessly only get mired in bizarre error messages before we ever got anywhere near creating a working Web page.

Anyway, I’d heard a podcast a while back where Michael Hartl was being interviewed about the Rails tutorial he’d written and the screencasts he’d created, and how he makes a really good living from people buying the screencasts and the PDF of the tutorial, even though the same content that’s in the PDF is available for free as Web pages. So this weekend I finally went and looked up http://ruby.railstutorial.org/ruby-on-rails-tutorial-book and started reading the first chapter of the tutorial book. And so far so good. I’ve done the first two chapters now and I like it. It’s up to date and it works.

gvim

The other thing I spent some time on was downloading, setting up and relearning vim (actually gvim). This is a lightly updated version of the UNIX vi editor. There’s a Windows version of gvim that lets you relive the experience of using a text editor originally created by a 22-year-old Bill Joy back in 1976. It might sound crazy to choose to go back to using vim, but I think it might make sense – there are some definite benefits.

I started using vi in 2001 when I got a job as a technical author and discovered, first day on the job, that I wouldn’t be using Word or even Notepad. I had a choice between vi and Emacs, neither of which I’d heard of before. I tried them both and settled on Emacs at the time, but since leaving that job I’ve never used Emacs again but I’ve used vi regularly over the years just because it’s always available on any UNIX/Linux server you ever connect to.

For a long time my text editor of choice was UltraEdit. I then switched to Notepad++ and I’ve stuck with it for the last eight or nine years now. But I thought I’d tie in learning Rails with brushing up my vi expertise (in the shape of gvim on Windows). I should point out that I’m working on Windows 7. So, after some tweaking of colours and window setup, and spending a little time revising the subject and creating a personal cheatsheet on vim (in vim), I’m using it quite happily now. I’ve never really been a mouse lover. I like keyboard shortcuts, and the great thing about vi is being able to keep your hands on the keyboard all the time: it really does allow you to get things done far quicker than you can by pointing, clicking, dragging.

git

git is another of those things I’ve been hearing about a lot over the past five years or so and felt I should find out more about. Back when I was learning vi and Emacs I was also learning about CVS, and I found it a steep learning curve. Fast forward a few years and, at my current job, we switched our version control from CVS to SVN and I came to really like SVN. I particularly like TortoiseSVN and its repo browser. But I’ve been thinking about looking at git for a while now – just to find out why people seem to like it better (it seems to be the most-used version control system for software source files now).

So I was pleased to discover that Michael Hartl’s tutorial gets you committing your Rails code to github right from the start. The only trouble I’ve had with the tutorial so far has been that I couldn’t push code up to github successfully to begin with and I struggled for a while (and posted a question on stackoverflow about it) before realising that I’d screwed up with one of my initial commands, meaning I had to delete the .git directory and start over. The problem was that I’d tried to push up my code before going to the github Web site and creating an account and a repository. Yes, I know: duh! But the problem seemed to be that having made this error, even though I then went and created the account and repository, something in my .git directory must have been messed up. So that held me up for a few hours, but – after backing up and redoing it – it now works fine.

The git commands are (like much in the world of Ruby on Rails, I suspect) the kind of thing that you just have to learn. It’s not obvious and you can’t just guess and figure it out. You need to know that exact words and syntax or it won’t work.

One of the things I like about having installed git from github is that I now have a bash shell on my Windows 7 machine. I can press the Windows key, type bash, press Enter and I get a console window with the bash shell, which allows you to do a lot more, a lot more easily than the standard Windows DOS-type command console.

Heroku

Finally, for this inaugural Rails Chronicle post, something else I’d heard about in a podcast but never used: Heroku. I spent a few days up in Glen Esk earlier this year and I remember one day walking the dog across the field to the river and than back up along the side of the Tarf listening to a podcast about Heroku, which is a hosting service for Web applications. Actually it’s more than that. It’s a system for continuous deployment of Web applications that’s intigrated with git to make it easy to push files up to Heroku’s cloud service and build a deployment that you can immediately browse to.

It seems to work incredibly easily and smoothly – but, again, working from the command line, you need to know the right commands; although these seem to amount to:

$ heroku create
$ git push heroku master
$ heroku rake db:migrate

Conclusion

So far so good. I’ve only done the first two chapters but they cover a whole lot of ground and I feel like I’ve learned a lot already. What I haven’t learned however, is any Ruby – so far.

However, periodically, after I haven’t used my local Web server for a while, I go to the XAMPP control panel, click to start Apache, but nothing happens. It doesn’t tell you there’s been a problem, but the “STARTED” indicator doesn’t appear.

The problem is that something else is hogging port 80. It might be IIS if you’re running that already, but more likely (in my case anyway) it’s Skype.

To solve this problem:

1. In Skype, go to Tools > Options > Advanced > Connection.
2. Clear the check box labelled “Use port 80 and 443 as alternatives for incoming connections”.
3. Click Save.
4. Quit and restart Skype.

Until a few years ago this blog was mainly a way for me to note down things that I thought might be useful:

a) To me, a few weeks or months later when I’d forgotten exactly how to do that thing I’d spent hours figuring out how to do
b) To someone else going through the same pain. I could save them a few hours of figuring out time

Most of the stuff I wrote about wasn’t about technical writing as such, it was mainly about the other things I was working on, or playing around with, usually in my free time. So, there’s stuff in here about Plone and Zope, there’s stuff about Perl, there’s stuff about C# and JavaScript. For example, back in August 2007, while learning C#, I worked out how to create a log file - so I noted it down:

http://www.itauthor.com/2007/08/21/writing-to-a-log-file-in-c/

So what changed? Well, the problem stems from vain ambition. For some bizarre reason I started to get interested in page views. I also think I had some notion of building up a reputation for myself as a documentation expert within the tech writing community. What was I thinking?

The result of this was that I started to restrict myself to writing about technical writing, and when I was thinking about what to blog about I began to think along the lines of: “What can I write about that technical writers might be interested in, so that I can improve ITauthor.com’s Google page ranking?” But it worked. Steadily more people were visiting the site. ITauthor posts were being linked to from other tech writing blogs, tweeted about by tech writers, mentioned in Parliament (OK, I made that last one up).

To make matters worse, the site was included in a couple of lists of influential technical writing blogs. The trouble with that was: it stirred up my competitive nature. I looked at some of the blogs above me in those lists and thought, “What’ve they got that I haven’t? How am I going to be further up that list next year?” Then I started getting people contacting me asking me to write about their products or services. Admittedly this was flattering, but now I was in the situation where there was an expectation on me to write certain things. No longer was the blog just a blog where I could dash off a quick note about something for my own future use. Now I had a reasonable expectation that people were actually reading what I wrote and some people were even waiting for me to write things. All of a sudden this seemed very familiar … hang on a minute … this felt just like … like … work!

ITauthor had turned into an unpaid job. And I’ve got several of those already: husband, father, gardener (well, very, very part-time gardener – you should see the state of our garden). I really didn’t need to give myself yet more unpaid work. My real, paying, job requires more than enough of my time, thought and energy.

So ITauthor entered a period of hibernation.

Is this me coming out of that blogging hibernation now? I don’t know. We’ll have to wait and see. What I do know is that I’ve realised that ITauthor.com is just my little personal blog. That’s all it ever has been. That’s all I now want it to be. I would quite like to start blogging again. But it’s got to be something I can do quickly and simply, without lots of prep. It’s got to be on my terms. It’s got to be about whatever I want it to be about: related to tech writing, or completely unrelated. And above everything else I’m not doing this for a living so it’s got to be fun again.

Until now, when I right-clicked a topic file in Flare’s Content Explorer and chose Open With, all I got, apart from the internal text editor and the internal browser, was a choice of either Firefox or Notepad (the simple Microsoft text editor):

I wanted to see Notepad++ in there. You might want to see Dreamweaver or something else. So here’s how to add programs to that menu.

Note: This procedure involves editing the Windows Registry. You need to treat the Registry with caution. Don’t go any further if you’re at all concerned about tweaking your Registry settings. You will also need to have an Administrator account. The following procedure worked for me today, using Windows 7. However, I provide no guarantees it will work for you.

1. First, check whether Windows knows where to find the executable file.

   To do this, enter run in the search box in the Start menu and press Enter.

   In the Run dialog box, enter the name of the executable file (e.g. notepad++.exe) and click OK.

   If the application starts it means Windows knows where this application lives. This reduces the number of steps in this procedure. If Windows does not find the application, but you know it’s installed, the process is a bit more complex and you should read ahead through the rest of the instructions before deciding whether you really want to proceed.

2. Start the Registry Editor.

   To do this, enter regedit in the search box in the Start menu and press Enter.

   If you have Windows UAC enabled (which you should have if you know what’s good for you), you’ll be asked to confirm that you want to allow the Registry Editor to make changes to your computer. Click Yes.

3. Expand the following sections of the Registry:

   HKEY_CLASSES_ROOT > .htm

4. Right-click the .htm folder and choose Export.

   Exporting a Registry key creates a file that you can double-click later, if things go wrong, to reinstate that part of the Registry.

5. Give the .reg file a suitable name (preferably something that tells you which part of the Registry it’s for and the date it was created) and save it somewhere appropriate.
6. Expand .htm > OpenWithList.
7. Right-click the OpenWithList folder and choose New > Key.  

   

8. Change the default name (New Key #1) to the next name of the executable file. In my case, for Notepad++ this was:

   notepad++.exe

9. Now do exactly the same thing for HKEY_CLASSES_ROOT > .html 

   Remember to export the key before you make any changes.

   If there is no OpenWithList key within .html just go ahead and add one.

10. If Windows found the application in step 1, you can close the Registry Editor, start Flare and check that there’s a new Open with option.

    

    Note: Changes to the Registry are applied immediately. There’s no File > Save menu item and you don’t need to apply your changes. However, you do need to close and restart Flare, if it was already running, before the application is displayed in the Open with submenu.

    If everything went okay, go back and archive or delete the .reg file you exported from the Windows Registry. It’s generally best not to leave .reg files lying around in case you accidentally run them at a later date and overwrite any Registry changes that were made since you created the export file.

11. If Windows doesn’t know where to find your application, you need to tell it. You do this with some more Registry tweaking.

    Warning: The following worked for me but I need to stress here: all messing around in the Windows Registry has a risk. I accept no responsibility for anything that might occur after you edit your Registry. Do not do this unless: you are confident you know what you’re doing in the Registry, you’ve exported any Registry keys before you make any changes, and you’re not going to hold me in any way responsible for any badness that happens after you’ve done this. You have been warned!

    So, having said that, imagine you have a program called qwoop that you want to use to edit Flare topic files. The path to the executable is D:\Alistairs Imaginary Software\Qwoop\qwoop.exe but entering just qwoop in the Run dialog box doesn’t start the application. 

12. Go to HKEY_CLASSES_ROOT > Applications
13. Within Applications, create the following hierarchy of keys (replacing qwoop with your own application’s name):

    qwoop.exe > shell > open > command 

    

    Of these, only command has any data.

14. Double-click the Default string entry in the command key and enter the path to the .exe file (in quotation marks if the path has spaces in it), followed by “%1” – this passes the name of the file you want to edit to the application for it to open.

    

15. Click OK.

    You should have something like this in the Registry Editor:

    

    Assuming you entered qwoop.exe as the name of the key within .htm > OpenWithList and .html > OpenWithList, in the first part of this procedure, Windows now knows what to do with this, because the new keys under Applications tell it where to find qwoop.exe.

16. Close the Registry Editor, start Flare and check that there’s a new Open with option.

    

It’s thick snow in my part of Edinburgh this morning. I just took the dog for a walk over the golf course – an exciting treat for her as she only ever gets to do that when it’s snowy – and I listened to the latest Hanselminutes show, all about remote working at Microsoft:

Show #242 - The Plight of the Remote Worker with Pete Brown

I'm a partial remote worker. What I mean by this is I work four days a week: two days from home, and the other two days I drive 50 miles to work in the office, then join the queues and crawl the 50 miles back again (a round trip of typically two and a half to three hours). Some of the points Scott Hanselman makes in this podcast struck a chord with me.

He mentions how remote workers are often paranoid about being perceived as not doing enough work, and how they over-compensate by working extra hard – or at least by working extra long hours. This is certainly true in my case. The days I work from home I always work in the evenings – partly because there are always things I’d planned to get done that day but I didn’t get finished by six o’ clock so I spend another couple of hours or so in the evening trying to finish things off. But I also feel obliged to work evenings because I remember that, when I went to make myself a coffee, I tidied up the kitchen while the kettle boiled and I feel guilty because I know I ended up spending 10 minutes doing that and I could have gone back to my computer and worked while the kettle boiled. The fact that, while at work, everybody spends time each day getting a coffee, chatting about non-work things, sitting in meeting rooms waiting for the meeting to get started, and a hundred other things that stop you getting stuff done in the office … that all seems not to count somehow. As a remote worker – to guard against the perception that you’re slacking off, watching daytime TV – you attempt to ensure you have spent a minimum of 8 hours doing productive work. Even if that means some of those hours are in the evening. Even if that means choosing work over time with your kids. Even if that means leaving your partner to prepare the evening meal, and then leaving her to watch TV alone for the rest of the evening.

The “remote guilt” that Scott talks about is a truly bad feature of working from home. Not only do many remote workers worry that they need to be seen as providing extra value to the company to justify working from home, they are often, nevertheless, seen by management as less committed members of staff than the high visibility folks who make sure they’re notice around the office every day (irrespective of the actual value the company is actually getting from them).

As a low visibility remote worker it’s hard not to feel that, if it came to a management meeting to discuss who to make redundant, you’d be a prime candidate: “Well, he’s good – but he’s never in the office.”

However, there are many great things about working from home, rather than commuting long distance to work. For example: not sitting in a car for three hours every day; not spending £60 on petrol; reducing your carbon footprint; getting more work done. And there are usually good reasons for not relocating nearer the office: not forcing your family to move away from friends and family; not forcing your partner to find a new job; continuing to live somewhere you like living.

So, if I sound like I’m bitching, I’m not. I choose to be a (partial) remote worker, and I like it. It just worries me, that’s all. 

Technology to make you more visible as a remote worker

Although Scott starts off the podcast by saying that Microsoft are not generally keen on remote working, it seems like they do, at least, have the technology to make the remote worker’s life easier. Scott talks about Microsoft Lync and Microsoft RoundTable. At Microsoft the issue seems to be getting people to use these technologies. For most of us though the issue would be getting our companies to invest in technology like this. The fear and paranoia of the remote worker tends to mean that, having been allowed to work from home, you accept that this is probably at the expense of any other discretionary goodness from your company (like pay rises) – so asking for anything that makes remote working less alienating, if it costs money, is probably not a good idea and you’d better just shut up, count yourself lucky and keep working those long hours. 

However, Microsoft RoundTable does sound great. Here’s a promo video for it. It’s an incredibly silly video, but it does give you the gist of what RoundTable is:

Finally, in January of this year, Scott put a video on Channel 9 showing the work Microsoft Research had been doing into "Embodied Social Proxies". This is something beyond video conference: having a physical presence in a meeting that you’re attending remotely.

It looks fabulous, but I think it’s going to be a long time before many companies invest in something like this:

The problem

The problem we’re trying to solve is how to debug a topic in a CHM file where you’ve got JavaScript that dynamically changes the HTML at runtime (i.e. when the topic is displayed in the Microsoft HTML Help viewer). If you’re debugging issues in WebHelp output you have the fabulous Firebug plugin that allows you (amongst other things) to click on objects in the output page and see what their HTML looks like right now. But unfortunately you can’t add Firebug to the help viewer. Or can you?

Online solution

This is the best solution, but it relies on you having:

• Internet access
• JavaScript enabled (a safe assumption as it’s probably JavaScript you’re debugging here)
• No firewall settings that might block code being downloaded from getfirebug.com (unlikely)

If any of the above aren’t true then you’ll need to use the offline solution (below).

The online solution uses the Firebug Lite bookmarklet to add much of the functionality of the Firebug plugin for Firefox to the browser pane within the HTML Help Viewer.

1. Do one of the following (these are just alternative ways of copying the same JavaScript to the clipboard): 

   Either: Right-click this link – Firebug Lite – and copy the link location (“Copy Shortcut” in IE).

   Or: Copy the following code:

   javascript:(function(F,i,r,e,b,u,g,L,I,T,E){if(F.getElementById(b))return;E=F[i+'NS']&&F.documentElement.namespaceURI;E=E?F[i+'NS'](E,'script'):F[i]('script');E[r]('id',b);E[r]('src',I+g+T);E[r](b,u);(F[e]('head')[0]||F[e]('body')[0]).appendChild(E);E=new%20Image;E[r]('src',I+L);})(document,'createElement','setAttribute','getElementsByTagName','FirebugLite','4','firebug-lite.js','releases/lite/latest/skin/xp/sprite.png','https://getfirebug.com/','#startOpened');

2. Right-click the title bar of the HTML Help Viewer.

3. Choose Jump to URL.

   

4. In the Jump to URL dialog box, paste the text you copied in step 1.

   

5. Click OK.

   After a moment (while it downloads files) the Firebug panes are displayed across the bottom of the browser pane in the HTML Help viewer.

6. Click Inspect, then click an object in the topic pane.

   The HTML for this object (including any dynamic modifications) is displayed in the HTML tab of the main Firebug pane:

   

Note: External JavaScript and CSS files aren’t recognised because they reside at another domain. So, when you click the CSS tab all you’ll see it “There are no rules in this stylesheet” and in the Script tab you’ll get “Access to restricted URI denied”. However, the functionality of the HTML tab is enough to make this technique extremely valuable for debugging.

Offline solution

The alternative is just to display the current, dynamically modified HTML in the browser pane. You can then select and copy/paste it into an editor for debugging.

To do this, copy and paste the following JavaScript into the Jump to URL dialog box:

javascript:'<xmp>'+window.document.documentElement.outerHTML+'</xmp>';

Note: The xmp element is deprecated and you shouldn't generally use it. However, in this case we know that we're using it in IE (the browser part of the HTML Help viewer) and IE, as of writing, still supports this element. If this stops being the case in future, the following is a less elegant (but standards-compliant) way of doing the same thing:

javascript:'<pre>'+window.document.documentElement.outerHTML.replace(/</g,'&lt;')+'</pre>';

Almost certainly the issue here is that itcc.dll is not registered. This must be registered on the PC on which the CHM file is compiled. After the CHM has been built, registering itcc.dll has no effect on the existing CHM – the Search tab still won’t work. You need to register itcc.dll and then rebuild the HTML Help output.

I’ve just run across this problem with Madcap Flare 6.1, but this is not a Flare problem. itcc.dll is Microsoft’s HTML Help Workshop, an old, old Microsoft DLL that Flare uses when compiling the CHM file. If this DLL wasn’t registered successfully by the Flare installer, or if it gets unregistered (which seems to happen now and again for no apparent reason), then you need to register it manually.

To register itcc.dll in Windows Vista or Windows 7:

1. In the search box at the bottom of the Windows start menu, type cmd.
2. In the result list, right-click cmd.exe and choose Run as administrator.

   Note: This is important. If you have Windows UAC enabled (you should!), then you won’t be able to register the DLL unless you do so as an administrator (even if you’re logged on as a user with administrator privileges).

3. In the command console window, type: regsvr32 itcc.dll and press Enter.

   A message is displayed confirming that the DLL was registered successfully.

   

4. Restart Flare and rebuild the CHM output.

Related post: Fixing Search in Flare HTML Help.

Giving commands cryptic names just to save a few key presses might seem weird but if everything has to be typed at a command line, then the shorter the command the better – once you’ve memorised them. And the cryptic names have the added benefit of bolstering the guru culture that ruled in programming until IDEs like Visual Studio spoiled the party by allowing any snot-nosed kid to create great software just by selecting from IntelliSense popups. [I’m joking – just in case that isn’t clear.  :-) ]

PHP also has its shorthand, and today – thanks to this fact – I wasted a good 10 minutes scratching my head over a broken PHP script I wrote back in 2006.

The script was outputting this in a form field on the Web page:

<?=trim($fields['issuetext'])?>

I couldn’t figure out why. I knew it had been working before. And, yes, I was running the PHP from a different Web server – but my phpinfo.php page showed me that PHP was working okay. I realised that <?=trim was non-standard, but changing it to <?php =trim broke the page entirely, and I knew it had been working okay before.

The answer, this page eventually reminded me,  is that <?=WHATEVER?> is the PHP shorthand for <?php echo(WHATEVER) ?> and to make it work you need to set short_open_tag to “On” in the server’s php.ini file.

Scrolling down my phpinfo.php page confirmed that I didn’t have this enabled:

Memo to self:
Think twice before doing stuff that’ll save me seconds today if it might cost me (or someone else) minutes of aggravation in 6 or 12 months time.

The two I’ve been using recently are jsbin and pastebin.

For example:

• http://jsbin.com/ejoye4/edit – click Preview to see the output
• http://pastebin.me/6ddbefe3185f806d5903c7ab5664a673 – click EDIT CODE to see the code

In this post I describe how (with the help of jQuery’s $.ajax() function) to use the existence of a file on the server as a switch to determine behaviour in the browser.

Case study

In my case, the problem I had was that I use Madcap Flare to generate WebHelp output, and sometimes I want to build a customer version of the WebHelp and other times I want to build an internal version that has issue reporting functionality turned on. This adds little icons to the page that call some PHP for reporting, listing or searching for issues for the current page in the help system.

The issue reporting functionality is governed by a Javascript file, and I want to use a Flare condition to turn that functionality on or off. Flare can’t condition lines within a Javascript file to be included or not included in the output, but you can use Flare conditions to determine which files end up in the output. So I wanted a little bit of Javascript that said: if a particular file exists on the server turn on the issue reporting functionality, otherwise leave it turned off.

As with so many things Javascript, jQuery makes this easy.

Code

Here’s the jQuery code. Obviously you can replace the alert statements with something more useful.

$.ajax({
    url:'/somedirectory/onyourserver/filetofind.html', 
    type:'HEAD',
    error:
        function(){
            alert("ERROR: File not found. \n:-(");
        },
    success:
        function(){
            alert("Nice one! File found. \n8-)");
        }
});

Note: The file isn’t important. It’s purely being used as a switch. The file I use as the switch is actually the barest of bare-bones HTML files that is valid XHTML (which Flare demands). The type:'HEAD' statement in the code tells browsers just to request the HTTP response header for the file, not the contents of the file. However, as this is not supported on all browsers, you should only use this method if you know that the file being used as the switch is either empty of very small.

Try it out

To try this out, go to:
http://jsbin.com/avalo4/2/edit

Click Preview to see the output. You should see the “File found” message.

Click Code, change the file name in the Javascript and click Preview again and this time (assuming the file doesn’t exist on the jsbin.com Web site) you’ll get the error message.

If you’re checking in several files in Madcap Flare (e.g. File > Source Control > Project > Check In All) and you get the error:

The given key was not present in the dictionary.

Then try checking files in individually, or in smaller batches, from the Pending Check-Ins panel.

It worked for me!

Do you want Adobe Acrobat to erase your hard disk?

Igor Ljubuncic's article 5 cool Notepad++ tricks gives you some reasons why you might want to switch from plain old Notepad.

Also it's free.

If you use twitter you'll be familiar with the concept of URL shortening. You want to tweet about that video where the dog thinks its own leg is trying to steal the bone but you've only got 140 characters to say what the video is and include the link to YouTube. URL shorteners allow you to change:

http://www.youtube.com/watch?v=tJgMueh-zLM&feature=youtu.be
to:
http://bit.ly/dfzFE6

Even if you don't use twitter URL shorteners can come in handy. For example, at the beginning and end of the ITauthor podcast I use some music by Amplifico and I like to put a link to their page on musically.com in the MP3 description that you can read on your iPod when you're listening to the podcast. It's much nicer to give the URL http://tinyurl.com/amplifico, rather than http://www.musicalley.com/music/listeners/artistdetails.php?BandHash=cdef1ecef0d12844ed816b922fcada5d.

Some popular URL shorteners

• tinyurl – This was the first URL shortener most of us will have come across - way back before twitter appeared and ramped up demand for short URLs, leading to a proliferation of shortening services.
• bit.ly – twitter supported use of bit.ly which made it a popular service. Recently there have been doubts raised about the wisdom of using a Libyan registered domain (.ly) as the Libyan government have said they will take down domains that contain immoral content.
• j.mp – This is just bit.ly but with 2 fewer characters. If you already have a bit.ly URL you can use the same shortened path, stick it on the end of the j.mp domain and save yourself those 2 precious characters. For example, the dog video gets shortened to http://j.mp/dfzFE6.
• goo.gl – Google are one of the many big companies that have now got into the URL shortening business.
• is.gd – just a nice simple Web page that produces nice short URLs.
• ... I could go on, but there's not a whole lot of difference between these services.

Your very own URL shortener

Shortening URLs isn't difficult to do and there are a selection of free URL shorteners that allow you to produce your own short URLs. All you need is your own Web site and your own domain name. So, for example, I own the domain name itauthor.com, so I can produce short URLs like http://itauthor.com/1 or (more descriptively) http://itauthor.com/podcast36.

The solution I'm using is called yourls. It's a series of PHP scripts with a MySQL database behind it. So if you're already running a Web site based on PHP and MySQL (for example, a WordPress blog) then you've already got everything you need. Just upload it and browse to the admin page. The yourls contains all the instructions you need.

The only problem I had was as a result of some changes not getting written to my .htaccess file in my root Web directory. I had to go and manually add the following at the start of the .htaccess file :

# BEGIN YOURLS
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{HTTP_HOST} !^itauthor.com$
RewriteRule . - [S=3]
RewriteRule ^([0-9A-Za-z]+)/?$ /yourls-go.php?id=$1 [L]
RewriteRule ^([0-9A-Za-z]+)\+/?$ /yourls-infos.php?id=$1 [L]
RewriteRule ^([0-9A-Za-z]+)\+all/?$ /yourls-infos.php?id=$1&all=1 [L]
</IfModule>
# END YOURLS

You don't need the two lines highlighted in red if you're not running WordPress, or anything similar that relies on being able to rewrite URLs. The yourls documentation says, in this situation, you need to put all the yourls files and directories in a subdirectory of your root Web directory (e.g. in a directory called "u"). However, this means that you need to include the subdirectory in the YOURLS_SITE configuration setting and it'll then be part of the shortened URL (e.g. http://itauthor.com/u/123, which kind of defeats the purpose. So the two red lines get around this by diverting URLs without "www" to yourls.

The first of the red lines says "only apply the following rule if the URL doesn't begin http://itauthor.com". The second red line says "if the previous condition resolved as true then skip the following three rules".

This seems a bit like a double negative but it's necessary because RewriteCond only applies to the RewriteRule that immediately follows it, so we need the skip rule. The result is that, on my site, the three RewriteRules that divert page requests to the yourls PHP scripts are only applied to URLs beginning http://itauthor.com. The "[L]" means "last" - in other words, if this RewriteRule is applied don't go any further, so we never reach the rules that WordPress uses, which are further down the .htaccess file. If a URL begins http://www.itauthor.com then the yourls rules are skipped and the URL is processed using the WordPress rules.

This means that http://itauthor.com/2 is sent to yourls to retrieve the original, long URL from its database, whereas http://www.itauthor.com/podcasts is sent to WordPress to create a Web page using content from its database.

What's the point?

Well, okay, there's really no point other than a bit of personal domain name vanity. Why have your tweets full of bit.ly or goo.gl URLs when you could have your own domain name showing up – even if clicking the link doesn't take your tweet readers to your Web site.

And to finish, just because I find it very funny, here's that video of the back leg bone thief:

In this podcast I describe why Acrobat shared review is so good and why the closest things I could find (WebNotes and SharedCopy) just don't do what I'm looking for.

Links

• Acrobat Pro: http://www.adobe.com/products/acrobatpro.html
   
• WebNotes: http://www.webnotes.net/
  
• SharedCopy: http://sharedcopy.com/
  

This video shows how to configure and create a shared review in Acrobat Pro. Because it goes through the configuration steps for setting things up, it makes it all look much more time-consuming than it actually is. Once you've set this up, generating the shared review is simple. We used the same internal server approach demonstrated here (using a WebDav folder on the server) and it works really well for us.

Today I posted an ITauthor podcast onto this site. And the comparative ease and difficulty of the two process became immediately apparent.

Although I have some niggles with AudioBoo (there are some very obvious improvements they could make), it certainly does make publishing a podcast very, very easy. This is especially true if:

a) you have an iPhone
b) you're happy to record your podcast episodes directly into your phone and post them without any editing

Editing is the bane of podcasting - so I actually see a lack of editing as a good thing. However, the bad thing is that you can't slip over 5 minutes. If you try to post a recording that's longer than 5 minutes then it just stops dead after 4.59.

I don't have an iPhone, so my experience was a degraded one of recording onto a little digital recording, uploading to my computer, uploading a photo from my Blackberry, then uploading recording and photo to AudioBoo via the upload web page. But even still, it was way, way quicker than how I currently produce my ITauthor podcast. Here's the ridiculously complicated process I trawl through for that:

1. Record the podcast.
2. Upload it to my PC.
3. Edit it in Audacity.
4. Export it as a .wav file (I've tried exporting to MP3 but the sound quality is rubbish).
5. Convert the .wav file to MP3 using Format Factory.
6. Add tags and photo to the MP3 using ID3-TagIT 3.
7. Upload the MP3 to my Dreamhost server using WinSCP.
8. Open a previous ITauthor podcast blog post in Live Writer.
9. Copy it and use this to create a new blog post.
10. Post this to my WordPress blog as a draft.
11. Go to the web page for editing the blog post and add the MP3 using the Blubrry PowerPress plugin.
12. Publish the blog post.

This is a long and tedious enough process to discourage me from podcasting regularly.

There's got to be a better way. And if all you want is a mini, 5-minute podcast then AudioBoo probably is that better way.

Didn't have my camera with me, but I snapped these with my Blackberry:

View Full Album

Hi, I'm playing with a new idea - or actually a retread of an old idea of mine - an Audio Blog! I just quickly recorded a bunch of my thoughts and put them into a MP3 file to post here:

That was three years before podcasting really started to take off. And the thing that I really liked was the idea of listening to someone rather than having to sit there reading. The internet is still quite a texty medium (think of Twitter, and even FaceBook - although some people, insanely, keep all their photos there - is still largely just text), but back then in 2002, boy did you spend a lot of time reading off a flickering CRT! I spent most of my working day reading, so, although I liked the idea of blogs, sometimes the reading of them felt like a bit of a chore. Hearing the voice of a blogger you'd been reading for a long time was wonderful. As Russell says: "instead of just reading their thoughts you could hear their voices ... their inflexion and their enthusiasm". I was really surprised that audioblogging didn't take off and even Russell Beattie gave it up after a short while.

Then of course podcasting came along and for a while everybody who leapt on the idea thought they were broadcasting to the world when in fact, to begin with at least, the only people listening were other podcasters. And yes, I've made sporadic stabs at podcasting myself - and hope to do so again. My plans are currently on hold thanks to the utterly abysmal internet service I currently endure from Sky Broadband which makes any sort of internet experience tedious at best and renders the recording of Skype interviews completely unfeasible ... but I digress.

Now there's an easy way to do pretty much what Russell Beattie was doing back in 2002, it's called Audioboo. It's an application for the iPhone, Android and the Web that allows you to record up to 5 minutes of audio, tag it and post it to your Audioboo profile. They've branded these recordings "boos" - which gives you a clue as to how this must have been pitched to the venture capitalists who no doubt funded the site: trendy social media, with an audio twist. However, for podcast lovers like myself a really nice feature is that every tag and profile has an RSS feed, which means you can subscribe to any of these as a podcast.

Sounds great. And it could be great if it wasn't so difficult to find anything worth listening to. The problem is the lack of classification. I want to find people who generally record stuff on a certain subject, but there's no way to do this, other than stumbling upon something by blind luck. The only way to find "boos" is to browse:

• everyone's boos (the most recent boos: completely random)
• featured boos (also seemingly random - you just don't get all the "This is a test" recordings of people trying out AudioBoo)
• popular boos (a perplexing selection if these are really the most listened to recordings - the list is also strangely static)

On the iPhone you can also browse for boos that have been geotagged to somewhere near to your current location. I can see how this might occasionally throw up interesting recordings. Unfortunately I don't own an iPhone.

However, there's no classification of booers (boozers?), so it's impossible to find people who might be talking about things you want to listen to. Yes there's tagging, but try searching for "software" and you just get a ragbag of boos that people decided to tag as "software". What I'm looking for are people who generally record their thoughts about software.

This highlights the problem with tagging versus less free-for-all methods of classification. If AudioBoo allowed people to choose to classify their profile with a maximum of three keywords, only the people who generally talked about software would choose "software" as their classification. Then I'd be able to find them.

It's frustrating because I'm sure there is a lot of audio in Audioboo that I'd enjoy listening to. I just can't find it. I can try, but all the rubbish and nonsense is going to put me off the effort very quickly. It's like a going into a huge library to find something to read, but the books are stacked in a completely random order and they have unmarked spines so I have to open them up, one by one, to find out which book each one is. After opening a couple of cheesy romances, a car repair manual, several books in foreign languages and a biography of a 1980s cricketer I give up and head home to buy something off Amazon.

Good luck Audioboo, but I can't see me visiting very often until you put a bit of thought into usability.

Source: Bonnier

I wouldn't have liked to have rushed out and bought an iPad having previously watched this video because, while all the other proud owners were swooning over their new toy, I think I might have been disappointed that it didn't match up to what I'd seen in this video.

You can read more about the creation of this video and the subsequent creation of an iPad application that used some of the Mag+ concepts on the website of BERG, the design consultancy that worked on the video: http://berglondon.com/projects/magplus/

The problem

I created a video in Camtasia and output it as a Flash file to put on a website. I chose FLV format in Camtasia, but the file that runs initially is a .swf file. This displays a little animation and shows the first frame with a big play button on top. It all worked fine locally on my PC but when I uploaded it to the website it just displayed as a black box with no initial animation. This suggested a problem with the .swf file and, sure enough, when I tried loading the .swf file directly in the browser all I got was a grey page (that's gray for anyone Googling for that spelling).

The debugging

The strange thing was that I'd previously added another video elsewhere on the site and it worked fine. It wasn't anything to do with the size of the .flv file because the working video had a larger .flv file, and anyway I was convinced the problem was the .swf file.

My immediate thought was that it was a permissions problem. So I blew the permissions wide open but it wasn't that. I then thought it could be a security issue but telling the browser to trust the website didn't help either.

I'd actually added this within the help authoring tool Madcap Flare, and this took me down all sorts of wrong paths. And, eventually, paths were the problem. I fell back to more Googling and eventually came across a Techsmith forum post by "Showland" that had the solution.

The solution

Showland's forum comment said:

Hi. I had this problem as well, where the compiled file would play locally but not over the Web. I discovered that it didn't like a super long path to the files. Once I stored them with a shorter path, the screencast played fine over the Web. Hope this helps!

Eureka!

The URL for my .swf file was something like this:

http://www.my.website.xyz/documentation/authoringDocs/videos/Flare-adding-glossary-popups-FLV/adding-glossary-popups_controller.swf

So I moved the file up the hierarchy and gave it a simple name:

http://www.my.website.xyz/documentation/authoringDocs/videos/test.swf

and, hey presto, it worked just fine.

I don't know what the character limit is, but it's worth bearing this in mind if you work with videos on websites.

So I happened to be resurrecting an old Yahoo email account this evening and I couldn't resist clicking the Help link to see how Yahoo do their online help. And, lo and behold: a big search box at the top with a well-chosen selection of links below.

It's an email system, so I tried searching for "spam" and I got a very decent set of results:

And clicking on a link took me to a nicely pitched little tutorial topic on avoiding spam:

So the result is that from the help page I just have to do a search and click a link to get straight to some useful help. That's how it should be to get help with something on a computer. Anything more complicated than that has a problem. 

In Word, type three hyphens, or three underline characters, then press Enter. With the default setup, Word will replace the characters you typed with a line that stretches across the whole text width on the page. Great if you want a divider to split up sections.

But now try deleting this line. Click below it and delete backwards. The line is immune to deletion. Try to select it. You can't.

The secret to deleting the line is understanding what Word did. The line isn't quite what it seems. In fact it's a border that is applied to the bottom of the previous paragraph.

So to delete it:

1. Click anywhere in the paragraph above where you were when you entered the three hyphens of underscores.
2. Choose Format > Borders and Shading.
3. Select the None border setting.
   
4. Click OK.

This meant getting Perl working on my laptop. It's pretty easy. So I thought I'd blog the steps involved.

Read on if you want to try writing some Perl but:

• You don't know how to get Perl set up
• You don't have access to a server where Perl is already set up
• You use Windows and you really don't want to become a Linux guru (at least not today)

There are a variety of ways to do this. This is just the way I used a few minutes ago. It uses XAMPP which means that, by the end of the process not only will you have Perl (one of the Ps in "XAMPP"), you'll also have the Apache Web Server, MySQL and PHP. In case you're wondering, the X apparently stands for cross-platform. You might not want all of these right now but, unless you're really tight for disk space, I'd advise getting them anyway. If you're ever going to do any Web development, having this package of technologies on your laptop, ready to switch on with the click of a button, is fantastically useful.

So here we go:

1. Browse to http://www.apachefriends.org/en/xampp-windows.html
2. Scroll down the page to the download section for XAMPP for Windows.
3. Click the link for the EXE file (content description: "Self-extracting RAR archive").
4. Once downloaded, double-click the xampp-win32-n.n.n.exe file and confirm you want to run it.

5. In the XAMPP for Windows dialog box, change the destination folder if required.

   The installer installs XAMPP in an xampp directory within the destination you specify. So if you leave the destination at C:\ then you'll get a C:\xampp directory. I prefer to install things in D:\programs, so I changed the destination to this.

   

6. Click Install.

   From here on it's just a case of following the on-screen instructions.

7. After XAMPP is installed,  open the Windows Control Panel and double-click System.
8. Under Tasks, click Advanced system settings.

9. In the System Properties dialog box, click Environment Variables.

   

   We're going to add the path to Perl to your system's Path environment variable, so that it knows where to find the Perl executable for running Perl programs.

10. In the Environment Variables dialog box, scroll down the list of system variables and double-click the entry for Path.

    

11. In the Edit System Variable dialog box, click in the Variable value field, move the cursor to the end of the text and add a semicolon followed by <destination>\xampp\perl\bin. For example, if you installed xampp in C:\ you would enter

    ;C:\xampp\perl\bin

    In my case, my path to Perl is D:\programs\xampp\perl\bin.

    

12. Click OK in this and the other two dialog boxes.

    We'll now test that Perl is installed correctly.

13. Click the Windows button (that is, go to what used to be called the Start menu).

14. Enter cmd into the search box.

    A command console window opens.

15. Enter: perl -v

    If everything's working correctly you'll get a message that shows the Perl version that's installed - for example:

    This is perl, v5.10.1

    

    What this means is that, once you have a Perl script, you'll be able to cd to the directory in the command console and run the script by entering perl myscript.pl.

16. Close the command console window.

    Now we're going to start doing the interesting stuff: writing a Perl script.

17. Open you're favourite text editor - for example, Notepad++.

18. Enter the following:

    #!D:\programs\xampp\perl\bin\perl.exe      use strict;
    use warnings;     print "Hello world!\n";
    print "Press Return to exit.\n";   
    
       my $userInput = <>;

    
    Note: You'll need to change the first line to match the path to perl.exe on your computer.

19. Save the file as myscript.pl.

20. Open Windows Explorer and navigate to the folder where you saved the script.

21. Right-click myscript.pl and choose Open With > Choose Default Program.

22. In the Open With dialog box, click Browse.

23. Browse to your perl\bin directory and double-click perl.exe.

24. In the Open With dialog box, select the check box labelled Always use the selected program to open this kind of file and click OK.

     

    You've now associated the .pl file name extension with the perl.exe executable. Windows now knows to use perl.exe to run .pl files.

    So let's test it out.

25. In Windows Explorer, double-click myscript.pl.

26. A command console window opens to run the script. Our two lines are printed to standard output (in layman's terms they're displayed) and (thanks to $userInput = <>) the script waits for you to enter something before exiting. If you didn't have this line the console window would just close and you wouldn't have time to read what was on the screen.

    

    Job done. From now on you can write Perl scripts in your text editor and run them by just double-clicking the file in Windows Explorer.

So what?

Yeh, okay, so it's just another "Hello world!" program.

But now that you've got Perl set up and you know how to run a program, you can go off and learn to do lots of stuff with Perl.

Me, I'm going off to write a Perl script that will run every half an hour to: parse a table on a "Revision history" Web page within a WebHelp site generated from Madcap Flare, look for new rows in the table (i.e. details of new changes to the WebHelp) and, if it finds any, email the details to a mailing list and then alter the HTML of the Web page adding a style tag to the rows to indicate that the mailing list has been mailed the details.

I hope you find this useful. Drop me a comment to let me know.

perl /home/alistair/scripts/myscript.pl

Great, so now you set up a cron job so that the script will run automatically. For example, let's say you want to run it every Monday morning at 4.20 am:

20 4 * * 1 perl /home/alistair/scripts/myscript.pl

 
However, when this runs it generates the following email:

Your "cron" job on myserver
perl /home/alistair/scripts/myscript.pl

Can't locate DBI.pm in @INC (@INC contains: /usr/perl5/5.6.1/lib/sun4-solaris-64int /usr/perl5/5.6.1/lib /usr/perl5/site_perl/5.6.1/sun4-solaris-64int /usr/perl5/site_perl/5.6.1 /usr/perl5/site_perl /usr/perl5/vendor_perl/5.6.1/sun4-solaris-64int /usr/perl5/vendor_perl/5.6.1 /usr/perl5/vendor_perl .) at /home/alistair/scripts/myscript.pl line 15.
BEGIN failed--compilation aborted at /home/alistair/scripts/myscript.pl line 15.

 
What this means is that your script uses a Perl module (in this example, DBI.pm) which can't be found. The error message shows all the paths in the @INC list of paths where Perl looks for modules. So, for some reason, Perl found the module when you ran the script, but didn't find the module when cron ran the script as you.

The reason is that cron doesn't run in the same environment that you're using. When you connect to the server, you probably automatically change to your preferred shell (e.g. csh, ksh or bash) and load up a whole set of environment variables. This happens within the startup file – for example, .bashrc or .cshrc. But cron doesn't load up any of this, and it uses sh by default.

To see what's in @INC within your environment use this command:

perl -le 'print for grep {$_ ne q{.}and -d} @INC'

 
And you'll probably notice differences between the output you get and the contents of @INC listed in the error message.

So, to make sure @INC contains the necessary paths in any environment, load it up from within your Perl script. To do this, add something like the following to the top of your Perl script, just after the path to Perl:

BEGIN {
     push @INC,( '/usr/local/lib/perl5/5.8.2/sun4-solaris',
          '/usr/local/lib/perl5/site_perl/5.8.2/sun4-solaris',
          '/usr/local/lib/perl5/site_perl/5.8.0/sun4-solaris',
          '/usr/local/lib/perl5/site_perl/5.6.1/sun4-solaris' );
}

So now Perl will be able to find the missing Perl module. Sorted! Well maybe not.

If you now try running the script from the cron job you may get something like:

Your "cron" job on myserver
perl /home/alistair/scripts/myscript.pl

ld.so.1: perl: fatal: relocation error: file /usr/local/lib/perl5/site_perl/5.8.0/sun4-solaris/auto/DBI/DBI.so: symbol Perl_PerlIO_stderr: referenced symbol not found Killed

Now it's complaining about not finding something called ld.so.1. The problem here is with your PATH.

On my server, ld.so.1 lives in /usr/lib. You should be able to find out where ld.so.1 is by running:

whereis ld.so.1

/usr/lib isn't exactly an obscure place to look, but it's not in the PATH when the cron job runs. So the easy solution is to explicitly set the contents of the PATH environment variable in the cron job:

20 4 * * 1 PATH=/usr/local/bin:/usr/bin:/usr/sbin:/usr/lib; perl /home/alistair/scripts/myscript.pl

Now, just before the Perl script is run, the PATH gets set to three paths: /usr/local/bin, /usr/bin, /usr/sbin and /usr/lib. The syntax used here is that required by the sh shell in which cron runs.

At last, job done. The script runs and you'll be emailed any output it generates.

The context menu for a span in Flare 5

Madcap Flare 6.1 has been out for a while now and, if you haven't already, you really should upgrade to it if you're a Flare user – and if you're a tech writer and you're not using Flare to produce online help then do yourself a favour and go and take a look at it.

Release 6.1 is confirmation that Flare is the best documentation creation tool out there. In particular, for me, this release is important because it allows you to use Subversion (SVN) from within Flare, which was broken in 6.0.

However ...

Isn't it annoying when a new release of a software application removes something that you'd got used to using in previous releases? In Flare 6.1 – for no discernable reason – you can no longer change the attributes of a span by clicking on the "span" marker. We use the Name attribute of a span with a certain class to create a link to our own home-grown glossary popups. This worked great in previous releases, as follows:

• Select a word or phrase
• Choose span.glossPop from the Styles list
• Click "span" > Name
• Add the appropriate glossary reference

In 6.1 you can't do this any more. Now, just to increase your click count, you have to get to the Manage Named Elements dialog box from the Format menu.

Okay, so there's a workaround. But why remove something that was useful and we'd got used to using? Is it a bug or is there some sort of rationale to this change? I'll raise a Support call and report back.

But in my view more clicks to achieve the same result is never a good thing.

I have some PHP script that grabs some data out of a MySQL table. However, rather than display it in the normal way:

I want to swap round the rows and columns so that I display it like this:

The thing to be aware of is that when you use mysql_fetch_assoc to get stuff out of a database, for example:

while($resultArray = mysql_fetch_assoc($selectQuery)) {
    Do stuff here ...
}

what you get back is an associative array (that's a hash for folks like me who learnt this stuff in Perl before arriving at PHP). So in the above example $resultArray is an associative array - that is, a set of key/value pairs where the key is the field name and the value is the value in that field for that record. Each iteration through the while loop you get a different record.

So, in effect, it's like an array of associative arrays.

However, what you want in order to be able to swap round fields and columns is an associative array of arrays - that is, a set of key/value pairs where each key is a field name and each value is an array of the values for that field in each record in the data set. So what you need to do is:

• Iterate through each record in the data set (i.e. each row in your results) .
• For each field in the record, assign the field value to an array, a reference to which is the value of the key/value pair in the outer associative array.

If it sounds complicated, then I'm glad I'm not the only one. Actually, it's probably easier to understand by looking at the code:

assocArrayOfArrays-example-PrettyPrinting.html - This is a syntax-highlighted representation of the PHP.
assocArrayOfArrays-example.php.txt - This is the actual PHP saved as a .txt file so that you can see and download it.

And here's the PHP in action:
assocArrayOfArrays-example.php

And, lo and behold, version control is now working again in release 6.1.

Thanks Madcap - much appreciated!

In discussing what a manager can do, faced with this situation, he quotes President Harry Truman:

It is amazing what you can accomplish if you do not care who gets the credit.

10 useful tips from Chris Sullivan, Director of Technical Communication and Social Media at AVST

As I write my download connection is 0.06 Mb/s. Yes, that's right, a measly 60 kilobits per second. That means a long, long wait between clicking a link on a Web page and eventually having the result page in a readable state in front of you.

At this speed iTunes and Tweetdeck simply don't work.

This, I'm assuming, is due to Sky's wonderful Traffic Management policy: the more useful you find the internet, the more we're going to try and discourage you from using it.

So I logged into my Sky account and went to try and raise a Support call. Here's the form they present you with, saying: "tell us about your query":

What?!!! In that space? Now they're really just rubbing salt in my wounds.

OK, so, after writing out my complaint elsewhere and then copying it into this field and submitting it, lo and behold, as I suspected (but didn't want to assume, in case I had to get all the way back there again if I was wrong) there's a follow-up screen where you can pick from options and then you can send Sky Support an email. But honestly! Usability: ever heard of it Sky? Did you ever roadtest this on anyone? Did you ever think how it feels to spend 10 minutes on a grindingly slow connection waiting for pages to slowly load, just to get to this page.

So I'm off to have a cold beer now, watch some football and cool down a bit.

And maybe by tomorrow this page will have uploaded to Web host. And maybe Sky will get back to me. But at the moment I'm not optimistic.

But spelling's different. Isn't it?

Surely we can never afford to lower our defences against misspelling? Spelling comes in two flavours: right and wrong. Right? And if you let spelling errors slip through then no one will be able to understand what you're on about. One spelling slip and your credibility crumbles ...  You get the picture.

Well, that's what I've always thought. So I was surprisingly interested in an email Patricia forwarded on to me today. "Surprisingly" because it was one of those pass-it-on emails that used to do the rounds but which, thankfully, you don't get so much any more. Usually they have a list of lame jokes or pictures and at the end they tell you to email it to your friends. Usually I save them straight to my Trash folder. But this one contained some simple editing-type tests (for example, spotting a single N in a block of Ms) and then ended with this:

I cdnuolt blveiee that I cluod aulaclty uesdnatnrd what I was rdanieg. The phaonmneal pweor of the hmuan mnid, aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it dseno't mtaetr in what oerdr the ltteres in a word are, the olny iproamtnt tihng is that the frsit and last ltteer be in the rghit pclae. The rset can be a taotl mses and you can still raed it whotuit a pboerlm. This is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the word as a wlohe. Azanmig huh? Yaeh and I awlyas tghuhot slpeling was ipmorantt! If you can raed this forwrad it 

It is amazing how easy it is to read this. And it did make me stop and ask myself: maybe I should lay off the obsessive marking up of every piddling little spelling mistake when I'm sent documents to review. As long as the first and last letter are correct, why worry?

Yeh, right!

I take a liberal, progressive approach to grammar. But I think I'll stick to my hard-line approach to spelling.

A loved child has many names.

I'd like to think that maybe the multiplicity of titles given to people who do the same or similar role as me suggests that we are a well beloved function within our organisations. However, experience tends to suggest otherwise. More likely is that the many names signify an identity crisis in the profession, or an attempt at aggrandisement or a search for job security - or a mixture of these and other factors.

Whatever the reason, I thought I'd list some of the names I've come across for jobs that, behind the title, can sometimes be very similar:

• communications officer
• content curator
• documentation developer
• e-learning author
• information architect
• information designer
• information engineer
• knowledge engineer
• technical author (inf. tech author or TA)
• technical communicator
• technical writer (inf: tech writer)
• user assistance developer

Have you come across any others?

This got a little bit nearer with HTML5, but Firefox 3.6 doesn't support MP3 files (which most people still use for audio files on the Web), just Ogg Vorbis. IE9, on the other hand, supports MP3 but not Ogg.

There is a jQuery plugin called jPlayer which goes part of the way to providing a cross-browser solution, but it's a very techie solution and not easy to configure.

So, until all of this gets sorted out finally, most of us just follow the path of least resistance and use a Flash-based audio player and accept that, because Steve Jobs is on a crusade to kill off Flash, no one browsing your pages on an iPhone or an iPad is going to see the player.

As I write this, in June 2010, the podcast pages I produce to accompany my podcasts use a Flash player that comes as part of the Blubrry PowerPress plugin for WordPress. And at the top of the sidebar on each page I use the Easylistener player. Here's a screenshot, just to remember it by, as it's only a matter of time before I have to remove it:

I periodically scour the internet for small, nice-looking audio players that can be pointed at an RSS feed, and Easylistener is the only one I've found that I really like.

William White describes the origins of Easylistener:

Easylistener was developed in the Yahoo! Media Innovation Group by William White and Joseph Magnani. It was inspired by the work of Fabricio Zuardi, Lucas Gonze and many other amazing and talented engineers working for Yahoo! Music in San Diego and Santa Monica, who were developing the Yahoo! Media Player.

Easylistener feeds off XSPF, a venerable XML format for playlists. The little chunk of code that places the player on your Web page includes a reference to a Web site that will take the URL of a Web page and will go and read that page, extract details of any audio files it finds and build them into XSPF that it then feeds back to the Easylistener Flash application.

The trouble is all of this was developed by Yahoo! and they provided the "playthispage" service that produced the XSPF for the player. But Yahoo! lost interest in (or never really noticed) Easylistener, so it was left to rot. Back in July of last year I blogged that the URL for the "playthispage" service no longer worked, which resulted in no content appearing in the player. After a while they seemed to have moved it to another server and I got the player working again. However, it recently stopped again, and this time I was sure it was dead for good.

I emailed William White, who had commented on my original blog post, and I asked if he could help. He got back to me to say he'd set up a PHP script that provided the same XSPF generation service. As a result, for the time being, the player is working again.

To get it working again I added:

playthispage_url =http://musiclibre.org/playthispage/?url=

to the flashVars attribute within the embed element.

So my embed element now looks like this (note: the flashVars value should be one long string, I've broken it into lines here just for good looks):

<p style="margin-left:-10px; margin-top:0">         <embed src='http://l.yimg.com/us.yimg.com/i/mig/playlistbadge/25.swf?referer='          width='170'            height='200'            wmode='transparent'            flashVars='playlist_url=http://www.itauthor.com/category/podcasts/feed&             playthispage_url=http://musiclibre.org/playthispage/?url=&             rounded_corner=1&skin_color_1=0,-100,-29,18&skin_color_2=0,-100,-27,20'          type='application/x-shockwave-flash'            pluginspage='http://www.adobe.com/go/getflashplayer'        />                                                                              </p>  

However, if you  want to use Easylistener to your own Web pages, the easy way to get it is to go to:

http://www.musiclibre.org/easylistener/

There's a nice little Web application there for setting the page that gets scraped for content and choosing the way you want the player to look. You then just copy the embed code and change "http://webjay.org/flash/xspf_player" to either "http://musiclibre.org/xspf_player" or "http://musiclibre.org/dark_player".

For example, here's one I just went and grabbed.

And if you don't see anything (or the player is empty), it means it's broken again.

Such a shame Yahoo! didn't continue supporting this because it's still way better than anything else out there that tries to do the same thing.

Then this evening I read this blog post by Mark Metcalfe: Tech Writers Need to Learn to Say Yes

Maybe if I'd read this I would have set out the options, rather than saying no. However, I worry that it's not quite as easy as Mark suggests. Very often requests for time come out of the blue and the start date is today. If you give a qualified yes, the person may hear what they want to hear - the yes - and conveniently forget the discussion of workload, cost and priorities. Often you are responsible to deliver work for several people at a similar managerial level and each of them thinks their work is the priority. Escalating to a more senior managerial level can be problematic because escalation generally has to happen through one of the managers concerned, who have little incentive to trouble their boss for arbitration.

So maybe, as well as learning to say yes more often, the tech writer needs to learn diplomacy and negotiation skills. Give a tentative yes to everybody and then get them to sort it out between them. Get everybody in a room if possible. Who's going to give way, because there's only so much you can do? So doing C means rescheduling A and B.

But if doing C is the best thing for the company then it would be crazy not to do it just because you'd already planned to work full-time on A and B.

I'm not sure I agree with the order Ellis places these in, so this is my reordering (and rewording) of the four levels:

• Ask a friend - usually by instant messaging, maybe by text or email, increasingly via twitter
• Ask the local expert - Ellis calls this the 50-foot guru: "the person within 50 foot of your desk who is more knowledgeable than you"
• Search for help yourself - most of the time this means Googling for it. You might use another search engine, but Google remains the default means of finding information for most computer users
• Call support - this might mean phoning your internal IT helpdesk at work, or it might mean emailing the company that produces the software with a support question and then waiting for a reply

I haven't numbered this list because the order is debatable. Some people don't like admitting they don't know stuff, so they'll always search for themselves before asking someone else. Other people have the attitude: I've got a helpdesk and I'm gonna use it - and they'll pick up the phone to support whenever they get stuck. On the other hand, I suspect people increasingly aren't prepared to wait for a reply to a support call - they've got to have the answer right now, which is usually when a local expert is required. And then for some any excuse is a good excuse to text, tweet or instant message their friends.

These four levels relate particularly to younger users - Ellis says "primarily those under 27", I'm not sure why 27 specifically, but I know what he means. Google first emerged into the public consciousness in 1998, when today's 27 year olds were 15. By that time ICQ and AIM were well established instant messaging platforms. So people around that age and younger have lived their entire adult lives in the Google world, and often they've been using instant messaging as an everyday way of chatting to friends since they were in school. I definitely think people in their late twenties and below are less prepared to invest time digging around researching a subject to find answers than people over 40 (like me).

But even I sometimes don't bother looking up the documentation provided by the software company. In particular, these days I never bother looking up the help systems in Microsoft Office products. Experience has time and time again proved to me that it's simply a waste of time. There's obviously lots of information available from Microsoft - usually when you search the Word or Excel help you get lots of results - but you just spend far too long doing all the leg work, looking through page after page, and often don't find what you're looking for. Go to Google and search from there and you'll usually find the information you need among the hits on the first page of results.

But going back to the four levels of support identified by Ellis Pratt. What about the manual, he asks, where does that fit in? Well, in many cases, that's now one of those things users find by Googling:

many may not recognise it as a manual. It might not have an index, page numbers or a table of contents, but it serves the same function.

The traditional manual is, in most cases, an anachronism now. And traditional ways of creating documentation, based on the way we used to produce printed manuals, are equally anachronistic, even if they're now applied to creating online help. And hey, if most people get their answers about using an application by asking their friends or the local expert, do we even need documentation at all?

Well the answer is yes. Information still needs to be packaged and presented. It's just that this can be done in a different way now, and the information very often gets to the end consumer second or third hand. For a variety of psychological and sociological reasons there are still people who are prepared to invest time learning all about an application. This person becomes the guru. The guru gains some sort of reward from this role and he/she passes on the information to others, who can then share the information with their friends. These second-hand recipients of knowledge are not gurus but they can still, from time to time, supply answers to IMs or tweets asking for help.

Apart from the gurus, the other group that still regularly finds documentation useful is support staff. They'll search a help system on behalf of users who can't be bothered to do so for themselves. And the support staff may even be involved in writing the documentation (this is the ScreenSteps philosophy). Either way, the documentation is the knowledgebase or knowledge repository in which answers to users' questions are to be found, and the support staff can answer a support call with a link to a page in the documentation - typically a specific help topic.

As technical writers we should have no fear that there will be no work for us to do in a few years. Software is going to be around for some time to come and all but the simplest software applications need some sort of user assistance. But it might be that we're not working in a role called "technical writer" - and we almost certainly won't be writing traditional manuals with a title page, table of contents, chapters, appendixes and an index.

But then - despite what many people imagine - I believe most user assistance professionals aren't spending much of their time writing that sort of traditional manual right now anyway.

Next, after you've got a decent understanding of the subject matter, you then start looking at the application (what there is of it so far, plus any plans/designs/user stories you can find for what will be appearing in future iterations of work) and you talk to the project managers, developers and testers, and hopefully you also get to talk to some beta users or user advocates.

Then you can begin to plan your help system. What's the top-level structure going to look like? How are you going to break it down into sections and subsections. Several years ago I worked on a help system where we spent weeks drawing up a complete TOC for the help, and getting it reviewed and signed off, before we started writing a single topic. Needless to say, that was long before I'd heard of the Agile development approach.

But my previous couple of posts have got me thinking. If we could do away with the TOC maybe we could do away with any structure outside of individual topics. And if we could do that then we could cut out a lot of the preliminary process outlined above. It might mean we could get to the point of creating useful content much more quickly.

The ScreenSteps approach is worth considering here. It goes something like this:

• At initial release, the help system just contains 10-20 questions that you know users are likely to have
• After release of the software, the help system grows over time as users ask questions and you add the answers to those questions to the help. But note: you only add new content in response to real questions
• New help topics get dropped into the help as you write them. Users can find them in a search and you can send them a link that'll get them straight to that topic. Consumers of the help don't need a TOC.

The ScreenSteps Documentation home page is a great example of a simple documentation interface:

Notice how predominant the search box is. You could claim this page has a table of contents - it kind of does - but it's not like the traditional, elaborate expanding-tree TOCs you find in many online help systems. It's just a simple series of links. If you click one of these links you get to a similar page with more links, from which you go to an actual topic. So there's never more than one hierarchical level of links on screen at once, and you're never more than two clicks from a help topic.

And what I really like is that this allows you to keep adding topics without always having to decide where to place a link in a tree TOC. Just write the topic and get it in there for users to see. If it merits a link in one of the secondary links pages you can go and add one, but I'm pretty sure most people using this system will get to content via a search.

I'm convinced these days the majority of us are searchers rather than looker-uppers. So the search box serves the majority searcher community, and the links are there:

1. For the minority looker-uppers
2. To direct people quickly to popular topics. Hopefully you're able to use the logs from your web server to spot the topics that most people go to and you can design appropriate first and second-level links to get people there fast.

Maybe it's time to retire the old tri-pane online help:

Apologies to ESRI. I'm really not slagging their online help (acually I think it's very good). It's just the first internet-visible tri-pane WebHelp I could think of.

Tech Pubs have almost no interaction with actual users ... they rarely ask users what they need.

This lack of direct connection with end users means that tech pubs has no idea what information is actually important to their users. They don’t know what questions the users have. They don’t know how best to answer those questions. The end result is software documentation that meets the requirements of “stakeholders” but not users.

Guess what? The stakeholders aren’t going to use the documentation.

It's thought-provoking stuff. I also love an article on the bluemango website entitled "5 Steps to Improving Your Software Documentation". I think I love it because I feel like I wrote it myself. It sums up some of the things I believe in about documenting software - for example: make good use of screenshots and videos and, whatever you do, don't just go through the application screen by screen writing up a description of what's on each screen.

The guys at ScreenSteps also have an interesting take on planning documentation: don't plan.

You can't possibly anticipate every question your users will ask. So don't. Just: write down actual questions people have and then answer them.

This video, while being very much a marketing piece aimed at selling ScreenSteps, contains a lot of very sensible ideas that are worth thinking about:

The don't plan your documentation, just answer users' questions approach sounds great. But it requires a shift in how documentation gets created that will involve a whole restructuring of roles and responsibilities between departments. This might be too much of a leap for some businesses to make.

And what happens if you're working on a new system that hasn't got any users yet? This shouldn't be a problem if you have a truly Agile development process. In this case real live would-be users are getting their hands on beta versions of parts of the system at regular intervals, as it's being developed. The trick for those responsible in creating the documentation has got to be involvement in this process: tapping into the reactions of those early users, soliciting questions from them and using those questions to shape your documentation.

However, for old-style software development (long development cycles against long lists of requirements, followed by an eventual release) it's going to be difficult to use the ScreenSteps approach to come up with an initial help system.

Here's another ScreenSteps quote that echoes a personal mantra of mine:

People don't read documentation, they reference it.

Your users aren’t going to cuddle up by the fire and read your software manual. They are going to read it when they get “stuck” using your software. They are going to read it when they have a question. Make sure that your documentation makes it easy for them to find the answers to their questions.

This is something I repeatedly tell in-house staff (generally, but not exclusively, staff who've worked in the software development business for years) who still equate documentation with printed manuals and who expect technical writers to spend most of their time creating printed books. No! That's not what we're about. We're about helping users to get the most out of the software and we do that in whatever way is most effective - and that's usually not in the form of a printed book.

The bluemango website and their blog (Talking in Pictures) are worth having a browse around. Lots of really sound advice in there. Note: I'm not recommending ScreenSteps as a documentation platform - I've never used it, I just discovered it today - but it definitely looks like a great solution for documenting certain types of software applications.

http://www.bluemangolearning.com/blog/2010/05/who-should-write-your-software-documentation-not-tech-pubs/

I feel like I could have written this myself!

Tom describes helping out with user support for an application. He also works on the online help for this application. He describes how useful this contact with users can be. He writes:

I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

Talking to users. Wow! That's how it should work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. Our end users (yes, I know, horrible expression, but what I mean is not the administrative users, or the managers, or the customer’s support staff, and not the decision makers who you sold the system to originally but who will never actually use it, but the people who have to use the software day-in, day-out as part of their jobs) … hang on, let me start that sentence again. Our end users contact their internal support staff and, if they can't help, those support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we're in a different part of the building). So it's not unusual for tech writers to work on a product for months, or years, and never talk to an end user. Their knowledge of the end user tends to come second hand, through the product manager or some other SME. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

So Tom’s post got me thinking: maybe working periodically in support is something all tech writers should do.

Tom’s post also referred to an old ITauthor podcast where Graham and I discussed how much you should document. I must admit I’d completely forgotten about that one. I should probably listen to it again some time.

But what I think I probably said in that podcast, and it’s what I really believe, is that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I've seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It's the scatter-gun approach: "How should I know what users will want to know about? So I'm just going to document as much as possible."

I'm convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don't need help with that. It tends to be the secondary things - the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious - it's those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

Tom’s post and the comments after it talk about how, as a result of users asking questions, and perhaps contributing answers to user forums, a help system can continue to grow and improve. And it’s obviously a good idea: after the initial, good-enough-for-release version of the help, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

Tom, who I’m assuming works on hosted WebHelp, describes how whenever he gets a support question that is now answered in the help, he goes and writes a topic answering the question, rebuilds the help and then replies to the user with a reference to the new topic. I think this is a great idea, but it only works where you host the WebHelp. If your customers host the help on their own server, or if the online help is traditional client-side CHM files, then it can be months before users see the next version of the help system.

One of the comments I really liked was by Larry Kunz. He writes:

As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums - either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

Is this yet another alternative title for our role: information curator?

After commenting on the post I continued to mull it over, in particular the issue of finding information in a help system that just keeps growing and growing. Tom writes:

in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics

This gave me a radical thought. Isn’t it about time to do away with the TOC and the index in online help systems? Both the table of contents and the index features of printed books that were pulled across into online help, way before Google appeared in our lives, and maybe they’re just not appropriate for online help.

Surely what we need is really good search results. How do 99.9999…% of people find information online? Through a search engine. The more I think about it the more convinced I am that, if your online help had a great search engine, you wouldn’t need to worry about the system growing and growing as questions and feedback from users helped you add the information they wanted to find. Better still would be the situation where a user community forum helped you build into the help the answers to questions people had actually asked, rather than the tech writer’s best guess of what they might ask.

So come on help tool vendors, give us really good search results. The search functionality in Madcap Flare’s WebHelp leaves a lot to be desired - try doing quoted searches. If you publish WebHelp that’s publicly visible, you can use Google as your search engine and, while far from perfect, that’s probably going to give you the best available search results right now. But what if your WebHelp is hosted on an isolated corporate network? Or what if you’re tied to delivering old-style CHM help for the foreseeable future? Back to the help tool vendors in that case. Come on: give us really good search results.

From making a habit of talking to non-technical people about how they figure out how to use software, I’m convinced the majority of people wouldn’t bat an eyelid if the TOC and index disappeared from help system and the landing page for help was just a simple, Google-like page with a box to type in your question and a big old Search button.

I'm not sure I'm sold on Agilewords. How's it better than all the countless other ways of doing shared documents? How's it better for reviewing than Acrobat Pro?

But these tips are worth a look.

Technical writers in a software development department often feel like third-class citizens, with programmers as the top-dogs and testers being granted second-class status. This engenders a certain camaraderie between fellow poor relations, testers and tech writers, filling, as they do, roles that are sometimes viewed as subordinate or auxiliary to the majority party within the development department. The work of testers and tech writers often starts at around the same time, and both roles can be subject to "ship early" pressure to keep the time available to them to a minimum.

But like tech writers, testers - rightly - believe that what they do is a crucial, if undervalued, function for the creation of quality software products.

Amongst other things, I ask Richard:

• What is software testing?
• Why do we need testers? (Can't programmers just test their own code?)
• What's the difference between: unit tests, integration tests, regression tests, functional tests, user acceptance tests, lean testing ...?
• How do testers and programmers get on? (Don't programmers get really irritated by testers finding bugs in software the programmer thought was working fine?)
• Why can't we introduce automated testing and save on all the money we're paying all those testers?
• Are technical writers as useful to testers as testers are to technical writers?
• Who'd be a tester?

Got any thoughts on the matter? Leave a comment below.

For something completely different, have a read of Richard's blog:
ROCKETBOOTKID AND BOOSTERBOY'S PALACE OF RIGHTEOUS JUSTICE.

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