Month: August 2008

Testing Documentation

As part of the product, testing documentation seems like an obvious thing to do, but what does it really mean? I’ve fielded the question in a few different places now and it’s always interesting to delve deeper and understand the rationale behind the request.

“We should test the documentation”, seems like a harmless enough statement and I’ve heard it uttered in more than one place yet I’ve never worked in a company that actually tested the documentation.

Some clarification is usually required, of course, as there are many ways that you could test the documentation, for example:

  • For online help, test that any hooks from the application to the documentation work properly
  • Check that cross-references are corrected and, if hyperlinked, work properly
  • Test the content matches exactly what is on-screen
  • Test the flow of information is correct and makes sense from a users point of view

Now, we do test that our online help works correctly, that the correct page is launched from the application and that a sampling of internal links work correctly.

However, the last two items in the list can be a bit of a thornier issue. Testing the content is a much bigger job than most realise, presuming it is being done correctly and it also raises the fun issue of is this a bug in the documentation, or in the application.

Every time I’ve had this question asked I’ve said yes we should test the documentation, but what I really mean is that we should use the documentation to test the application. One method I’ve thought about is to have one person would read out the instructions, with another piloting the application. Just an idea but it would flag up some issues in both areas, I think.

Of course such resource heavy requirements rarely see the light of day and the simple fact is that we don’t test the content of our documentation. Yes we get it reviewed but they are separate (if closely related) things.

So, in an effort to close the gap between reviewing the documentation and testing the documentation, it is probably worthwhile running a short workshop for your development team, a 10 minute session that shows how best to review documentation. I’m planning such a workshop at the moment, so more on that, soon.

Finish This Sentence

Ignoring the fact I have been specifically tagged, and not completed, a few memes in the past couple of months, this one I think I can tackle. Thanks to Cliff for the open invite.

1. My uncle once: remembered my birthday (LOL!!).

2. Never in my life: have I chosen to eat a raw tomato, ick ick ick.

3. When I was five: I had the run of the house as my sister had yet to appear.

4. High school was: much the same as anyone else who was smarter than most and didn’t “fit in” with the cool kids.

5. I will never forget: finishing my first 10K and the emotions that went with that.

6. Once I met: a homeless person and bought him coffee and a doughnut.

7. There’s this girl I know: Who writes a blog that no-one reads, and she’s really good but hates getting compliments (and I’m not linking to it until I get permission).

8. Once, at a bar: I stole a bottle of champagne and no-one noticed.

9. By noon, I’m usually: ready for lunch and checking what the afternoon holds.

10. Last night: I did some work on a blog design, it’s coming along nicely (and the client is really nice, that helps).

11. If only I had: more discipline.

12. Next time I go to church: I’ll, again, wonder why I’m there.

13. What worries me most: is what the future may or may not hold.

14. When I turn my head left I see: a MacBook and the remnants of my lunch.

15. When I turn my head right I see: out of the window, across the cul-de-sac.

16. You know I’m lying when: I don’t tell the truth.

17. What I miss most about the Eighties is: ABSOLUTELY NOTHING!!.

18. If I were a character in Shakespeare I’d be: an obscure snob, sitting on the sidelines whilst the main play unfolded, chipping in with witty asides.

19. By this time next year: I’ll be a year older.

20. A better name for me would be: Mr. Research.

21. I have a hard time understanding: people who are happy to accept the status quo, who accept prejudice as fact and remain inconsiderate of others.

22. If I ever go back to school, I’ll: only be there to gloat.

23. You know I like you if: I smile when we talk.

24. If I ever won an award, the first person I would thank would be: whoever nominated me.

25. Take my advice, never: that plate of melted cheese? Don’t eat it.

26. My ideal breakfast is: filter coffee and toast with lashings of butter and honey.

27. A song I love but do not have is: the live version of Hotel California that they use on MTV sometimes (OK OK, Q or VH2).

28. If you visit my hometown, I suggest you: Climb up to the castle, and enjoy the view down the Clyde.

29. Why won’t people: just get along?

30. If you spend a night at my house: red wine and takeaway curry, good music and laughter.

31. I’d stop my wedding for: no-one as I’m already married, thanks!

32. The world could do without: idiots.

33. I’d rather lick the belly of a cockroach than: let ANYONE stick ANYTHING in my EYE EVER.

34. My favourite blonde(s) is/are: Marilyn Monroe.

35. Paper clips are more useful than: not having paper clips when you need one.

36. If I do anything well it’s: convincing people that I can do anything well.

37. I can’t help but: constantly need something to hold my attention.

38. I usually cry: at soppy movies, or soppy TV shows, or… basically any form of simple emotional manipulation and I tear up.

39. My advice to my child/nephew/niece: only you know what YOU really want, learn to listen to yourself.

40. And by the way: one day this blog will cease to exist.

And I’ll take the same route as Cliff and wimp out of nominating anyone in particular. Instead, if you haven’t blogged for a while or just fancy a change, grab the sentences and finish them yourself.

This and that

Summer holidays make it easy to keep on top of RSS feeds, and easier to spot some ace new blogs. Check out this one, I think it could be quite good.

My father-in-law is back in Scotland for the month, so we’re off to see him tonight and I’m really REALLY hoping he wants us to bring in a fish supper for dinner. I’ve not had fish and chips for ages and currently have a real craving for them.

XNeat Windows Manager is yet another application capable of doing some nice UI effects in Windows. Best of all, and the reason it wins out over many other similar applications for me, is that with it installed you can MIDDLE-CLICK TO CLOSE APPLICATIONS STRAIGHT FROM THE TASKBAR. Sounds simple I know but it’s a habit I use all the time in Firefox to close a tab, and it’s been bugging me for YEARS that I couldn’t do this in Windows until I stumble across XNeat.

A quick thanks to Daisy for nominating me for a Post of the Week award, I didn’t win but was quite surprised to see my name in the shortlist. Who knows, it might inspire me to indulge my creative side a little more often (there was a similar post later on last week too).

Since I bought my iPhone I’ve changed the way I think about how I work when I’m at home, and find myself leaning towards my MacBook more often than my PC, it’s just so much nicer to use. The only downside is the small screen and limited hard drive (my music collection is larger than my MacBook’s hard drive). So I’m looking to the Belkin Flip (DVI version) as a solution.

Physio tomorrow, we’ll see if the eccentric loading exercises I’ve been doing (and for a change I’ve been pretty good at remembering to do them!) have had an impact. They FEEL like they have, fingers crossed.

Usability Matters

Anyone working in the software industry will know the term “usability” and have a reasonable idea of what it entails. As a technical writer, a user advocate within the development team, there is typically an overlap between how we think, and how usability specialists think.

For starters, anyone who is delivering information should know who their audience is and why they require the information. With a good understanding of your audience, you will know what information they require because you will understand how they use your product.

It seems obvious yet it’s something that many people struggle with, and I wonder if it is partly because, rightly, usability is a distinct field which has many experts and practitioners.

However, many software companies do not have resource dedicated to usability as, and I don’t get to say this often, it’s often seen as less of a priority than technical writing.

Why does any of this matter to you as a technical writer? Because it’s another string to your bow, another item to add to your CV, and something else that will convince your boss that it’s worthwhile keeping you in the team.

And hey, it’s interesting stuff, a little task analysis of the requirements, some creative thinking, and an even better understanding of the product and then, if you are really lucky, you get to talk directly to users of your product.

I’m part of the ad-hoc usability team in my company, and whilst it can be challenging it is part of my job I hugely enjoy and which makes me a better technical writer, and that’s never a bad thing.

Weekender

Friday night – a LARGE meal and a few beers left me feeling a bit bleurgh, but it was a good laugh. Was quite happy to get the last train home for a change.

Saturday – lunch in Perth, absolutely first class meal, then off to Dunkeld to catch the bride and groom emerging from the cathedral, before we headed up to the Hilton for the reception. Very nice place that, right on the banks of the Tay, and the reception was in a marquee out in the grounds. I’ve still to sort through the 200-odd photos we took (although at one point Louise and her brother were having some sort of stupid photo face-off (I’m guessing Paul will win that one)).

Needless to say, being a Hilton hotel, the drinks were a little on the pricey side… I’m still not quite sure what came over me but I definitely recall paying £8.50 for a glass of wine!

And Sunday saw us visit Louise’s Aunt for a spot of lunch. We got home around 4pm to a very affectionate little cat, watched a movie (I am Legend… guff), and generally lazed about until bedtime.

And now it’s Monday. Already.

How was yours?

Writer River is back!

I dropped Tom an email about Writer River last week, and he alluded to some of the issues he mentions in his post in his reply. Little did I know that Writer River was soon to be hacked!

I love the idea behind the website though, so it’s good to see Tom is still keen on pushing things forward. If you previously registered I’d urge you to go back and register on the new version of the website. The premise is the same, a website which will collate the best Technical Communications stories and blog posts.

Head over to Writer River, the more people who sign up and join in, the better it will become.