ITauthor Podcast 39: 3 levels of Help

Oxford Bar sign

In a noisy Edinburgh pub, Graham Campbell and I quaff ale, breathe in coal smoke and discuss such matters as: three levels of Help ("guide me", "read more" and guided tours of the application), the challenge of translating software documentation, mixing DITA information types in a single Help topic, and the challenge for Brits writing in US English. Listen …



Podlove: A better way to publish podcasts

Podlove logo

Fed up with my previous WordPress podcast plugin I disabled it and recoded my podcasts posts by hand to add an HTML5 audio player. But then when I started up podcasting again recently I didn’t want to have to fiddle around in the HTML each time just to get the audio onto my website. I needed a better way to publish podcasts. I found one.  More …

Audio recording: sometimes simple is best

iPod NanoOver the years I’ve tried a variety of microphones and recording devices to get decent audio quality for my podcasts. The last podcast I did (Podcast 38) was done on the spur of the moment, so I didn’t have many options. I had my iPhone, an iPod Nano and a couple of sets of Blackberry earphones. The results were surprising.  More …

ITauthor Podcast 38: Documenting IT architecture

Andy TuckerAndy Tucker is Head of IT Strategy and Architecture at DWP, and an old friend. I asked him to explain what "architecture" is in the context of computer systems and software.  Listen …

ITauthor Podcast 37: Return of the Podcast

ITauthor Podcast logoBack by popular demand: the ITauthor Podcast. Graham Campbell and Alistair Christie dust off their microphones and get on a Skype call to chat about life as a technical writer. And OK, so I lied about the popular demand thing.    Listen …

The cauldron: a design & engineering masterpiece

Cauldron photographed from insideThe London 2012 Olympic cauldron was one of the most stunning works of art I’ve ever seen. When it was lit during the opening ceremony and its petals rose into a dome of flames I was genuinely moved. I was completely awestruck as its stalks kept rising and it became clear it was forming into a pillar of fire. 204 petals of flame coming together to burn as one for the two weeks of the Games. This post includes a BBC interview with the cauldron’s designer and a couple of videos about its creation. Read more

Classic technical writing schoolboy error

School fail mark image It’s great when an application contains an in-built help system and you don’t have to go and Google to find out how to do something. It’s also great when you search the help to find out how to do X and you find a topic that tells you exactly how to do X. But it’s really, really annoying when the help topic describes exactly how to do X using dialog box Y – but gives you absolutely no idea how to get to dialog box Y. Here’s an example.     Read more

Convert escaped Unicode to HTML entities

Unicode character image I’m posting this here just because I spent far too long looking for the solution before eventually finding the answer on Stackoverflow.

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.     Read more

For more posts see the list of recent posts, or click a month in the Archives calendar at the bottom of the panel on the right.