Landing Pads

Helicopter landing pad

I’m guessing that you don’t want to miss that landing pad because if you do you’ll end up ditched in the ocean, floating around aimlessly and with no real idea of what to do next. Can you imagine how horrifying it would be if that happened? Floating there, unable to get back to land and with who knows what swimming around underneath you…

Yet this is the predicament that many users of online help find themselves in, having strayed into the online help they have been cast into an ocean of information with no real idea of how to get back to shore. Ohhh sure, we tell ourselves that the there is an easy way to get to the information they want through our carefully crafted Table of Contents, or perhaps a more direct route can be navigated using that Index you toiled over for hours, or better yet if they use the Search functionality they’ll find what they want. Right?

And, ultimately, yes these mechanisms work. If you know how an Index is structured you can quite quickly navigate to a keyword that probably matches the information you are searching for and should, hopefully, take you almost directly to the very help topic you need. Same goes for the Table of Contents although they are a little more prescriptive and you need to know what you are looking for to be able to find it, and of course the Search will provide you with several help topics that are, probably, what you are looking for.

Meanwhile the sharks have gathered and are nibbling at your feet!

At the UA conference last year, Matthew Ellison gave a presentation on what he termed “Keystone Topics” and in the Summer edition of the ISTC Communicator magazine (again, chock full of good stuff, it’s worth the price of membership alone if you ask me) Paul Filby covers something similar, outlining how to provide “The perfect help-system landing page”.

And so, with all of that in mind that is my task today (yes, a Saturday).

The concept is simple enough. You create a single topic that will be displayed to the user when they bash our old friend the F1 button. That topic is unique to the help system and, based on context, can be used to display a smarter set of links to potentially useful information. If you have the means you could display the most commonly viewed topics or, as I’m doing, you can point to the start of several paths covering the most commonly used areas of the product.

I don’t expect to get ours right the first time round, but hopefully the concept will work. I’m including a small addition to the foot of each such topic, asking users to contact us if they have improvements. It’s only on the landing pages but I’m hoping it might drive a nice little cycle of innovation with direct feedback from the users driving the content of the landing pages in the future.

Hopefully the landing pages will give our users some where dry to stand and survey the land a little, with clear signs to help them get to where they want to go.

Why everything is changing

I’ve agreed to present at this years ISTC conference, and my topic will be blogging and technical communications. It’s a nice topic title, vague enough that I can stretch it in many ways, but specific enough that it has some natural constraints.

I’ll write up some of my thoughts here, naturally, but it’s interesting that I’m starting to see how other areas of the online world, the Web 2.0 vision of the future, are coming into play.

Case in point: Rhonda Bracey blogs about the presentation Tony Self gave, based on an article he wrote titled What if Readers Can’t Read? which I’d already read, and linked to in my monthly newsletter column for the ISTC. The premise of which is:

The fundamental shift away from traditional forms of written communication (books and documents) to new media (e-mail, social networking, collaboration spaces) is something that we as technical communicators should be attuned to. The shift is not just from paper to online media… the shift is also away from top-down, autocratic communication structures to democratic, peer-to-peer structures.

It’s an excellent, thought provoking article, whether you agree or disagree, and it’s made all the more powerful by some of the videos that Tony showed during his presentation, videos to which Rhonda has kindly provided links.

One of the videos is referenced heavily in Tony’s article so I thought I’d show it here as it’s quite a powerful message and something that should be shaping our thinking in the years to come.

Without blogging, I wouldn’t have come across this and this is a perfect example of why blogging can be so powerful, however you do need to be part of this online conversation to be able to catch these snippets.

Why I joined the ISTC

In their own words, the ISTC is:

the largest UK body representing professional communicators and information designers

I joined the ISTC a couple of years ago. They’ve been on my radar for a while now, but to be honest I’ve never been sure of what the benefits have been, nor have I found much need to be a member of a professional body. So what does the ISTC offer members? Well the ISTC website states that:

the ISTC offers opportunities to exchange views and information with other professional communicators. Members enjoy discounts, news, training events, networking and recognition of professional status including the use of FISTC or MISTC (for suitably qualified people).

OK, so you can now refer to me as Gordon McLean MISTC.

Yes, that’s much better than “Oi, twit!”.

I’ve been a member of various committees and charities in my time so there is one thing that I know holds true. When it comes to any organisation you get out what you put in, which would explain why I’ve recently been struggling to justify my ISTC membership.

It’s not that I don’t put in, I write a monthly column for the newsletter and happily volunteered to be on the newly formed members panel which is in the midst, thanks to the outstanding efforts of Rachel Potts reviewing those very same benefits that the ISTC offer.

And it’s not that I don’t get value back out, the ISTC mailing list has proven useful and I’m sure when I attend the conference this year, my first, I will learn a lot and benefit from speaking to my peers

So the question is, am I getting value for money?

Ultimately I believe I am, but I do feel I could be getting more. When I joined the ISTC I was already following some technical writing blogs and already had the beginnings of a network of people who were offering some good advice and interesting thoughts about this profession of ours. Some of those were discovered through the TechWR-L mailing list, others by chance encounters or links from other blogs. It’s the one thing that, as yet, the ISTC hasn’t really managed to grasp hold of, the idea that what they are facilitating is a community of like minded souls.

In a way an organisation such as the ISTC has the advantage over ad-hoc groups, given that all of the members have paid to be part of the organisation. It’ll be interesting to see the outcome of the review of member benefits, to see where the community aspect of being a member rates with everyone else. Perhaps it’s just me but I truly believe the ISTC would benefit from increasing the networking/community aspect of membership.

Small changes

Sometimes it’s the little things that add up to make something better.

The realisation that I probably post to Twitter more than I should hit home recently. I use Twitter to update my Facebook status and, as a few work colleagues can see my Facebook profile, one of the jovial nitwits has created a special Facebook group just for me, titled “Gordon Mclean cannot stop updating his status”.

However, despite jokingly suggesting I might stop using Twitter soon (it has jumped the shark, hasn’t it?) I don’t see that happening, in fact I’m still finding new ways to use it.

One of the first applications I put on my iPhone was Twitterific. It was good enough for me to buy the Pro version (not hugely expensive) and it’s been my Twitter client for a while now. However it does have some limitations and when I heard mention of Tweetie I thought I’d give it a try. One intriguing part was the Instapaper hook up it has built in, with one click I can add a link that someone posts to Twitter to my Instapaper account to read at a later date.

Now, a few months ago that wouldn’t have been much use but as more and more of my fellow peers (technical writers and their ilk) start using Twitter, and as I use Instapaper for marking articles and posts that might be useful to feature in the monthly column I write for the ISTC… well it’s a match made in … Tweaven? (sorry).

In other fascinating news, I’ve been tweaking this very blog a little, mainly adding in a better view of the comments. Those of you with a gravatar should see that now, those of you that don’t get a randomly generated pattern (or you can always sign up and get a gravatar, it’s free).

OK, I’m sure you are all in need of a lie down. What an exciting whirlwind of a life I lead, eh?

Meetings and Contacts

A quick reminder to those of you in the West of Scotland, there is an open meeting this evening to which you are invited. No agenda, just a chance to meet up with fellow technical writers. We are meeting at 7 p.m. in the offices of Sumerian in Glasgow city centre, at 19 Blythswood Square, Glasgow G2 4BG. Tea & coffee will be provided.

Thanks Katja for organising this, I’m looking forward to it as it’s always informative and interesting to meet fellow professionals. As my career progresses (or perhaps just because I’m getting older) I start to understand the true benefits of, what has now come to be known as, networking.

It’s the same reason I joined the ISTC, and also why this blog exists. I’ve been blogging, on a personal basis, for several years and have made some good friends so I have my own proof that blogging works as a way to network, to communicate.

It’s not that hard to quantify either. Directly because of this blog I realised how enthusiastic I am about my line of work, which made me want to get more involved which prompted the writing of a monthly column for the ISTC Newsletter and which also lead to my invitation to speak at the TICAD conference. I’ve swapped emails with technical writers from around the world and, quite genuinely, can say that through the blogs I follow I learn something new, if not every day, at least every week.

It can be hard to find the time to write posts, it can be hard to find something that I can write about (I try to steer clear of company specific issues), but it is rewarding and, I hope, of some use to others.

Networking isn’t easy. In a way I’m lucky as I have an outgoing personality, but the internet makes it so much easier. In saying that, it still doesn’t beat face to face communications so, if you are in the Glasgow area this evening, please come along.

Sudden need for habit

Everything happens at once. It’s always the way of these things, the calendar remains empty until, all of a sudden you realise you have a concert and a leaving do to attend one evening, and a day/evening session in the pub the next day.

Such is the case this coming Friday, Radiohead gig at Glasgow Green on Friday evening the same night my boss is having his leaving do (he’s sharing it with another member of staff who is leaving, double trouble!). I’m really looking forward to both, and only hope that I’m not so completely soaked that they don’t let me into the pub later on…

It’s also approaching the end of our release cycle at work, so things are starting to ramp up there. I’m launching a new website as well as writing up some of the new featuress in the product.

And as usual – why does my brain do this? why does it wait until I’m stupidly busy – I’ve also started looking at resurrecting Scottish Blogs. Hopefully I can build it using something that requires a lot less effort and administration that the previous, hand-coded, version required as I just don’t have the bandwidth at the moment.

One thing I’ve been struggling to do is get into a writing habit. I’ve never really had one for this website, but as I now have two blogs, and I contribute to the ISTC newsletter every month (and occasionally to the quarterly magazine), it’s something I really should try and foster. Perhaps moving the Playstation upstairs to where the computer is (running it through the monitor) was a bad idea after all..

Still, it’s not all bad. I’ve started doing a little exercise fairly regularly (physio stuff as well as a some work on flexibility and core strength) and I’ve managed to rediscover my reading mojo a little, so if nothing else I’m starting to find a balance. Of course all of the above is currently impacted by a certain football tournament but that’ll be over soon.

Hi there

A quick welcome to anyone visiting from the ISTC Communicator magazine. I feel a little spoiled getting two mentions in subsequent pages (10 & 12 if you are wondering) but I’m not really complaining.

Over the past year or so I’ve definitely got the feeling that the ISTC is changing, and it certainly feels like a more modern and dynamic organisation than it has seemed to be in the past. Perhaps that’s natural, but it’s amazing how little things like a redesign magazine and newsletter, and hopefully a new design for the website, can refocus the energies of those involved.

Anyway, thanks for dropping by, there are plenty of links and opinions to be found in the archives (scroll down a bit, they are on the right), and here are a few of the more popular posts:

Or perhaps you just want to download the RSS feeds.

A day in the life

As featured in the Spring 2008 edition of Communicator, the magazine for ISTC members.

I’m the Publications Team Lead at Graham Technology, a mid-sized (and growing) software company based in Scotland and like many people in this field, I have a wide range of duties. As well as the more traditional technical authoring work, I also manage resources, consider strategy and working practices for the team, and generally do my best to represent the user during development meetings. I also find myself spending time considering the information strategy of the company, investigating translation requirements, and keeping up to speed with the Technical Communications industry.

I joined Graham Technology just over a year ago and it’s my first time working in an Agile software environment. The development team use the Extreme Programming (XP) methodology and it’s taken a little getting used to, particularly as all my previous experience comes from more traditional teams, with long timescales, project managers with Gantt sheets and lots of process documentation to be completed.

There are specific challenges to working in an Agile environment and to a fair extent they shape my working day and, whilst everyday is different, they all start with the same thing. Caffeine.

I’m usually one of the first people in the office and, once the coffee machine is going, I take advantage of the peace and quiet to pick through the emails that have accumulated overnight. I monitor a variety of automated emails from different systems, all of which help me build a coherent view of what is happening during a release cycle.

We have a development arm in Jakarta so I take the time to sift through their work to check for any possible impact on the documentation. Anything that catches my eye is noted on an index card and stuck up on a dedicated whiteboard allowing anyone to see what is outstanding at any given time.

Next up is a quick check of the Publications build to make sure it has run successfully during the night. We currently use Webworks to generate Javahelp which is automatically compiled into the product each night; small changes are quickly actioned and committed to the documentation, and are then available in the next software build, keeping us in-line with the principles of Agile development.

The final set of generated emails I check are from our bug tracking system and they list what has been fixed or added in the past day. Again, anything that may impact the documentation is noted on an index card and added to the whiteboard. And, by now, the coffee is usually ready; milk and one sugar, please.

Last but not least, there may be requests for information that have come in from our Deployment staff out on customer sites. Sometimes all they need is a copy of a specific manual, other times it takes a little research to find the information they need. Once that’s done, I spend a little time skimming my RSS feeds for anything else of interest.

It’s now around 9am and the office is filling up. I typically have a few things to chase up from the previous day, and it’s a good time to have a few quick chats with the developers before they get too embroiled in their daily work.

Our Development Group is split into six distinct teams, with three technical authors covering their output from brand new features to bug fixes and product enhancements. Most of the teams have a standup meeting every day to take a quick look through the tasks that need to be completed, and during these I play user advocate, considering UI design and any information requirements that need considered. It’s a very dynamic and collaborative way of working.

Working within an Agile development environment means that things move fast and information flies in from all sorts of sources and directions. Monitoring email, changes to our internal Wiki, and chatting to the developers and testers in the teams are all part of a typical day. Placing yourself in the path of these streams of information is the best way to keep up to speed, and learn what is really happening on a day-to-day basis.

I also try and keep in touch with Marketing and Training to understand their plans and see if there is any cross-over with what we are doing in Publications. I’m striving to make our message more consistent, and improve the way we plan, design, create and distribute our product information, and maintaining direct lines of communication is crucial.

Part of my Team Lead role is to make sure the product documentation is meeting customer expectations. We have two products, a user-friendly out-of-the-box product which our Deployment staff extend using our development kit. Gathering requirements from the Deployment staff is a constant push-pull exercise and, as they are talking directly to the users of our out-of-the-box product they act as proxies who can be interviewed to make sure we are providing the right information, at the right level for the expected user.

The rest of my time is spent writing documentation. This is broken into three main types of work at any one time; small changes to the products which require less than half a day to complete, larger changes to the products which may take between a day and a week to complete, and documenting the brand new features that are being added to the product.

I start with a high-level plan of what is required and then trickle the information into the relevant document throughout the development cycle, handling changes in scope and requirements as they arise. I try and plan to work on small chunks of content, making it much easier to drop something if the requirement is descoped at any point (this is a key reason we are moving to single source our content) and I spend any additional time researching and learning the part of the product I’m working on, playing with the software regularly to make sure I fully understand both how it works and how it would most likely be used.

Like everyone else, I don’t really have a typical day. I do try and stick to plan for the first few hours but interruptions, conversations and changes of priority are all part of the challenge of working in a fast-paced software development company.

Hello to ISTC Communicator Readers

I got home this evening to find the next issue of Communicator sitting on the mat. Thankfully it was in one piece so obviously the cat hadn’t found it…

Anyway, just to confirm that, yes, I am the same Gordon McLean who features in the final piece in the magazine. Worryingly that means you now know what I look like, so I can only hope it doesn’t put you off visiting my blog again in the future.

I’m also going to be featuring in the monthly newsletter, but more on that when it happens.

The article was a “day in the life” style piece and although re-reading it brought a few omissions to mind, it remains a fairly accurate portrayal of a typical working day. Truth be told I don’t actually have many days like that at the moment as we are nearing a release date but the main bones of the article are still valid.

For those that aren’t ISTC members (and why not?) I’ll be posting a copy of the article soon, meanwhile I’m off to read the rest of the magazine.


Busy busy busy, so I’ll “borrow” this from a recent ISTC newsletter.

The Washington Post has published the winning submissions to its yearly neologism contest, in which readers are asked to supply alternate meanings for common words.

  1. Coffee (n.), the person upon whom one coughs.
  2. Flabbergasted (adj.), appalled over how much weight you have gained.
  3. Abdicate (v.), to give up all hope of ever having a flat stomach.
  4. Esplanade (v.), to attempt an explanation while drunk.
  5. Willy-nilly (adj.), impotent.
  6. Negligent (adj.), describes a condition in which you absentmindedly answer the door in your nightgown.
  7. Lymph (v.), to walk with a lisp.
  8. Gargoyle (n.), olive-flavored mouthwash.
  9. Flatulence (n.) emergency vehicle that picks you up after you are run over by a steamroller.
  10. Balderdash (n.), a rapidly receding hairline.
  11. Testicle (n.), a humorous question on an exam.
  12. Rectitude (n.), the formal, dignified bearing adopted by proctologists.
  13. Pokemon (n), a Rastafarian proctologist.
  14. Oyster (n.), a person who sprinkles his conversation with Yiddishisms.
  15. Frisbeetarianism (n.), (back by popular demand): The belief that, when you die, your Soul flies up onto the roof and gets stuck there.
  16. Circumvent (n.), an opening in the front of boxer shorts worn by Jewish men.

The Washington Post’s Style Invitational also asked readers to take any word from the dictionary, alter it by adding, subtracting, or changing one letter, and supply a new definition.

  1. Bozone (n.): The substance surrounding stupid people that stops bright ideas from penetrating. The bozone layer, unfortunately, shows little sign of breaking down in the near future.
  2. Foreploy (v.): Any misrepresentation about yourself for the purpose of getting laid.
  3. Cashtration (n.): The act of buying a house, which renders the subject financially impotent for an indefinite period.
  4. Giraffiti (n.): Vandalism spray-painted very, very high.
  5. Sarchasm (n.): The gulf between the author of sarcastic wit and the person who doesn’t get it.
  6. Inoculatte (v.): To take coffee intravenously when you are running late.
  7. Hipatitis (n.): Terminal coolness.
  8. Osteopornosis (n.): A degenerate disease. (This one got extra credit.)
  9. Karmageddon (n.): its like, when everybody is sending off all these really bad vibes, right? And then, like, the Earth explodes and it’s like, a serious bummer.
  10. Decafalon (n.): The grueling event of getting through the day consuming only things that are good for you.
  11. Glibido (v.): All talk and no action.
  12. Dopeler effect (n.): The tendency of stupid ideas to seem smarter when they come at you rapidly.
  13. Arachnoleptic fit (n.): The frantic dance performed just after you’ve accidentally walked through a spider web.
  14. Beelzebug (n.): Satan in the form of a mosquito that gets into your bedroom at three in the morning and cannot be cast out.
  15. Caterpallor (n.): The color you turn after finding half a grub in the fruit you’re eating.

Well, they made me laugh. And yes, you may have heard these before.