ITauthor

There's a Russian saying I once heard at a funeral. It goes like this:

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?

One of these days browsers will be able to play audio files natively. You'll just be able to write an audio element in the HTML, point it at either an audio file, or a list of audio files, or an RSS feed containing audio files, and it'll display a smart looking audio player in the Web page.

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=

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.

Our Sales Director phoned me up today and asked for help with some bid work that's coming up. I've already rearranged my plans for next week to help someone else with some other bid work, so I apologised and said no. As I was turning him down I was already feeling bad about it because I've made a point of telling people that tech writers should be involved in bid writing.

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.

In a recent post on the Cherryleaf Technical Authors Blog, Ellis Pratt describes four levels of support that users turn to when they need help using a piece of software.

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.

The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it? This is a period of talking to the product managers and subject matter experts and reading up on everything you can find that sheds light on the world in which the product will live.

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.