Month: March 2008

Moments of beauty

A few days I ago I mentioned finding the beauty in things and I had a perfect example this morning as I drove to work. A glorious view unfurled beneath me as I drove down the hill. As usual my camera was tucked away in my bag. Mind you I was on the motorway so couldn’t really stop..

The sun was up, white-yellow through clouds, wafting salmon pink mist across the city like a blanket. Sprawling chimneys and gangling tower blocks dangled through the cloud. Layers of light broke away towards the hills on the horizon, shading each rise and fall, buildings picked out in silhouette, windows flashing sunlight.

15 seconds later the road dipped and it was gone. A small moment but it took my breath away.

Getting to EXPERT

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

The question above was prompted by a presentation I attend last week, given by Paul Sherman on behalf of the Scottish Usability Professionals’ Association, entitled: THE PERPETUAL SUPER-NOVICE.

The basic premise is:

the tendency of people to stop learning about a digital product-whether it’s an operating system, desktop application, Web site, or hardware device.

A simple example: Someone who has learned that you can cut and paste text in Word by using the Edit menu options and the application doesn’t support them learning how to do the same thing in a more efficient manner.

Many applications (and the documentation that supports them) is aimed at either getting from beginner to novice level, or getting from some kind of mid-level up to expert. There is a huge gap in application design (and, again, the documentation that supports it) around helping users get the most from their usage of an application.

That mid-level area is what Paul refers to as the Super-Novice:

in the absence of extrinsic motivation, it seems that many people stay novices or, at most, become a form of knowledgeable novice that I call the super-novice. Super-novices know a lot about the limited parts of a system they use regularly and almost nothing about the other parts

Obviously the presentation was focussed on usability and application design, but it got me thinking about how documentation, or perhaps we should be calling it supporting information, suffers in the same way.

It’s fairly easy to get into the mindset of the beginner; presume the reader knows nothing and assume a level of learning in which to frame the information. Expert level information is a little trickier but could be stated as specialist, or niche, information.

But what of the super-novice? If we want people to get the most from our applications (and we do, don’t we?) how do we enable the super-novices and help them become experts?

Paul touched on some of the aspects of web 2.0 communities, and how providing “achievement motivation” is a key method for enabling learning and helping build the “need for mastery”. At this point it is easy to see that traditional documentation, printed manuals or online help, will fail the user in this aspect. It simply can’t respond to the differing needs of the audience.

Of course there is still a requirement for those carriers of static information, but to really enable your users you need to start thinking beyond a simple push of information.

Looking at the current crop of social media networks and communities, it’s easy to pick out some common themes; there is always a core group of users who will soon become forum experts, reliable and helpful members of the group. These are the experts and the challenge is to help everyone else get to their level.

I’m still not entirely sure HOW one goes about that, but it’s clear that if this is an issue you can identify with, and that your audience acknowledges, then you need to start looking around for some new models of learning. The internet is full of them, just find a burgeoning online community and see how things work there and try and match it to your own audience.

The times they are a’changing, and those gaps in your documentation will only get bigger and soon, alongside the application, you may start to lose your audience. We need to consider those gaps, the line between A and B, and figure out how to help our users traverse it safely.


Paul writes on usability issues (and more) on his blog, and for UX Matters where the origin of the presentation can be found (and from which the quotes in the post were taken).


What is it about these things, these events in life that all seem to collide. Days go by with only the merest ripple distorting the norm then … BLAMMO! …

For example, take tomorrow. I need to be in the office to deliver a presentation as part of our induction and the kitchen fitters are due to, finally, start work. I’ve also got an appointment with the nurse to get my blood pressure taken.

I’d figured out the timings, I’d wait until the kitchen fitters arrived and then head to work. The presentation is right after lunch, so I’d give that then head off to the local health centre, then home to see how the fitters are doing.

Except they won’t be here until midday apparently, which fucks up everything. I can’t NOT be in work tomorrow but can’t wait here until midday… so Louise is taking the day off.

It’s never simple, is it?

Mind you, fate sometimes helps. I’ve managed to bork the search page on my other blog, so when I heard WordPress 2.5 was out I figured I may as well grab it and get upgraded. So I have. Both blogs are now on 2.5 and the upgrade was super smooth and whilst I’ve not had much time to play with it, the new admin screens aren’t too bad.

Fate, sometimes it gives you a helping hand, sometimes it’s like a steel-toecapped boot to your knackers. Such is life.

In other news, isn’t the new R.E.M. album good! They’ve rediscovered loud rockin’ guitars, wheeeee.

Explorer showing multiple desktops?

Windows XP has a bug in it, one that has bugged me for ages but is under the “can be tolerated” category. I’ve looked for a fix before but couldn’t find anything, mainly because it’s hard to describe within search terms (note to Google: how about searches based on uploaded screenshots??).

The problem occurs when you open Windows Explorer and start browsing folders. The tree on the left starts to show additional items named “Desktop” but, when you click on them they are actually items that are on your Desktop.. it’s a little weird and after a while you can end up with multiple “Desktops items at the top (and middle) of the tree on the left.
Read More

Recently Read

Been a while since I did one of these and, as ever, they reflect some of the things that have caught my eye over the past week or so. A couple of things on DITA which have me rethinking my approach towards it, and a some links to posts discussing … welll community, social media, Web 2.0 kind of stuff, some of it is a little away from my world but it’s good to get a different point of view on these things.

Docbook versus DITA
Not the first comparison I’ve seen but an excellent summary comparison of DocBook versus DITA. Whilst it was written by someone who admits that they were looking to portray a favourable outcome for DocBook, it’s an well-balanced set of information and will be useful to many.

From Free to Three ($100K)
One of the issues I have with DITA is the cost associated with implementing a complete end to end solution, something that, apparently, I’ve been mistaken about:

Our DITA Tools from A to Z section on the DITA Users website lists every software and service up to those $300,000 publishing solutions. But our policy of free member access to online tools means that anyone anywhere in the world can at least get started (our membership fees range from free to $100 a year).

We call our approach “DITA from A to B,” authoring to building and, of course, publishing structured content.

Definitely something I’ll be checking out.

Agile Content Development

Social media represents such a fantastic opportunity because it allows us to create and launch media properties directly to the public. But even more of a blessing is the direct and indirect feedback process that naturally happens in this space.

You put something out there, and the crowd will reveal the direction you should go. It’s not necessarily always the wisdom of the crowd, but rather the desires and objections of the crowd that guide you.

Use of social media needs fear

What about all of the fears of potential liabilities, losing control, and (the night terror) negative comments? IRRELEVANT! All are either uncontrollable (and were all along) or can be mitigated with good policies, procedures and education. Social media carries as much risk as email. You should be more afraid of losing the battle for relevance.

Is IT in danger of becoming extinct?
I’m not entirely convinced but, once again, this post suggests that there is a shift of balance, and that shift is entirely driven by users and their new found abilities to build communities around, or away from, your products.

Social media empowers users at the expense of IT. Enterprise 2.0 companies marginalize IT by putting powerful tools directly into the hands of non-technical workers, bypassing IT in the process.

No searching…

I’ve been trying, unsuccessfully, to add a better (Google) search to this site. Alas because I have a hand-coded WordPress theme, and I last looked at it about a year ago, I’ve managed to bork the search results location.

So, for now, the search isn’t working. Nuts.

Thanks to Tom, it’s all working now, and it’s even better!

A few random things…

Twitter continues to absorb, offering an instant outlet for tiny thoughts and today was Muxtape day. As ever, Meg was near the front of the list, but I soon followed along. Completely illegal I’m sure so I don’t expect it to last…

Asaph has caught my eye as I continue to find a way to gather together my online life, although I’ll happily admit that these days I’m not as bothered, or driven, to find a ‘solution’ as I’m not really seeing it as a problem.

I have two blogs, a Twitter account, a Flickr account and follow copious amounts of sources via RSS. I’ve stopped watching feeds that aren’t full (with very rare and limited exceptions) and I’m quite happy with my ‘online life’. I’ve made my peace with not reading EVERYTHING that crosses my path, letting my own internal filters deal with it as best they see fit. Hey, I also delete emails… shocking I know.

I’m enjoyable busy at work, and currently looking at things like Drupal and Joomla, and possibly Ning as part of a slight shift in my role.

I’ve still not sorted through my books, but we have some time this weekend so I might take a stab at it at some point. We are off into uncharted territory on Saturday, visiting Peggy, and Sunday will be the last day without a kitchen. My letter of complaint is primed and ready (still to send it to the people who generously offered to comment on it, must remember to do that).

Building work has started opposite our office, and the piledriver started today, leaving a nice shockwave rippling across to our office and shaking my monitors ever-so-slightly. You know, just enough to make me feel nauseous. Every 5 minutes or so… bleuch.

Also need to get car tax sorted, order some Florints, organise the tiler, figure out how I’m going to do the flooring in the kitchen, do a little tidying up in the garden and… so on and so forth.

As usual, a lot of little things going on. Most of which I won’t ever mention again!

I see no… photos

Flicking through Flickr … ahhhh I get it now …


I was … ummm … browsing Flickr last night and it struck me that I’m just not generally of a mind to take photos. I’m still very much a “go and take photos” type of photographer, rather than a “quick, take a snapshot” type of photographer. Now I’ll admit that, in the grand scheme of things, this isn’t really that big a deal but, as we all know, it’s the minor things that tend to piss us off and this, currently, is one of mine.

Before I continue I’ll point out that, as I type, my camera sits in the bag at my feet. It’s been there for the past couple of weeks (in the bag, not at my feet).

The lack of photos is not for the want of subjects either, for a start the building I work in has an art deco frontage and a modern glass, copper and metal extension, and even then I do seem to have a fairly good eye for composition (ohhh modesty, wherefore art thou?) even if my technical know-how still needs to be improved. No, I’m definitely not short of subjects.

So, I have the camera, I have the subjects. What on earth could possibly be stopping me taking more photos? Ahhh yes, of course. The idiot holding the camera of course!

Despite the fact I see many things, on a daily basis, that I think would make interesting snapshots (a shaft of light burning through the air, a discarded bike by the side of the road, the blossoming smoke rising from an industrial chimney) my camera remains unsheathed. I really, really need to get over this. But how?

I guess I just need to get over myself, get over the sense of… what? awkwardness? Not sure but I need to get my mindset sorted. Right. OK. Yes!!

In fact I’m going to take the first step right now.


My camera is now on my desk.

Hey, baby steps and all that..

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.