Month: October 2009

bookmark_borderDumping the manual

Posted on

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase.

It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies.

Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online).

So why do we still maintain this view of how information should be provided?

There is a level of comfort in having a table of contents and a structure to the information available when writing technical information. It allows you to make sure all the required information is in place, but most of the research I’ve read, and most of the anecdotal evidence I’ve heard, suggests that those lovingly created table of contents are not heavily used.

The index is another area, hell it’s another profession altogether, that we spend a lot of time crafting and rightly so as it is used by many people to navigate their way through a document.

But one thing that trumps both of these methods isn’t available in printed documents but is widely available for online information. Search.

OK, so none of what I’m saying is new, or revolutionary, far from it. Those of us who have been creating online help, regardless of the format (a lot of which was before the internet was popularised), know that if there is a search option available, it will be used.

With that in mind, and this is most definitely something we will be consulting with our users about, we are toying with the idea of dumping the index and the table of contents, making sure the content has a good set of internal reference links so users (power and novice alike) can find “paths” through the information, and switching the front page to be a Google-esque search.

Luckily we can pilot this approach whilst still producing the Javahelp, PDFs and HTML (Webhelp in Author-it terms) output so we don’t completely alienate our users. It’ll be interesting to see outcome.

bookmark_borderYearly Ritual

Posted on

I have a ritual on mornings like this. I wake up with a level of excitement, take a deep breath to steady myself, get up and walk calmly to the window.

I throw open the curtains, don’t worry I don’t ALWAYS sleep naked so the chances of my dangling bits being on show are minimal, and as my my pupils dilate as they adjust to the sudden change of light, I peer out into the street below.

Typically there isn’t much going on. I might see our cat heading off for another adventure, or the local squirrel foraging for the last nuts of the year (remember I’m usually clothed, and anyway he isn’t allowed into the house), or perhaps one of the neighbours is out walking their dog. Basically take your own suburban scenario, the run of the mill morning activities of fetching in the milk, or going to buy a paper, that is what is playing outside of my window. Nothing out of the ordinary, nothing different, nothing new.

This ritual of mine only occurs on two days of the year, and I’ve long past the point where I’m surprised by what I see.

The simple fact is that I enjoy this silly little ritual, for most rituals are silly, aren’t they, when you step back from them they are a series of utterly pointless actions but, as a whole they recognise that the entire point of the ritual is important to you (which also allows for the rituals to be based around silly and pointless things themselves). This applies to the ‘superstitious’ sportswomen who must always put on her left sock before her right, or the businessman pausing to inhale his coffee before taking that first sip of the morning. Both are ritualistic and in their own way rather silly, but to the person who has initiated the ritual they are important and have far deeper a meaning than is obvious to the observer.

I mention all of this as a way to deflect from the true nature of what I was going to say, in short, I digress.

This very morning I followed the same pattern as I always do on this day of the year. I woke up and, upon realising the day, I smiled to myself and levered myself into a sitting position. I took a deep breath and got up. I walked slowly and calmly to the window, reached up and took hold of the curtains. Another deep breath was taken and as my lungs reached maximum capacity (this is an important detail of this ritual), I flung the curtains open, and looked down and out into the street.

And, once more, for the 36th year running, THERE WAS NO FUCKING FERRARI SITTING IN THE DRIVE!!!

I exhaled noisily and go back bed.

Happy fuckin birthday to me.

bookmark_borderSelling ourselves

Posted on

Like many, I struggle at times with a common perception, one which was highlighted to me yesterday by a colleague.

Like most team leads/managers, I have a lot of tasks that aren’t purely focussed on the creation of information. I don’t do much technical writing, instead letting the guys in my team focus on that (they are better at it than me anyway) whilst I work around the edges of what they do, things like taking a document through a review with some SMEs and processing the output, or building a new output template, or proof reading some of their work.

My team and I have a good idea of what I do, even though I also get dragged into chats about other information related initiatives (document management systems being the latest). But as far as everyone else in the organisation goes, I am obviously not doing a good enough job communicating that out.

So my colleague was asking how my team were doing as we are approaching the last few weeks of this current release cycle. When I said that it was a bit tight and we were probably going to have to move some of the ‘could have’ information, he asked why and then asked what I was working on myself.

Thankfully, to answer his question I have a whiteboard directly behind me that holds all the ‘other’ stuff that technical writing teams need to think about; Product Glossary updates, creation of a Knowledge Centre, Release Notes and so on.

However the point here is that, whilst we all struggle to convey the importance of what we do (until people get to that “ahhhhh” point which most do eventually), it is in all our interests to evangelise our services. Yes this will only have direct impact within your current organisation but the ripple effect over the coming years will start to grow as people move on and take your messages with them.

It may mean that you, and your team, need to stand up in front of the whole company to ‘introduce’ themselves and what they do (same applies for lone writers!), as well as backing that up with updates and conversations with people you may not normally chat to, and I realise it’s probably not something that comes naturally to many people.

So to give you a kick start, as soon as I’ve finished it, I’ll be sharing a sanitised version of that very presentation. It’ll be focussed on a software company which is being re-introduced to that wee team they all know of, but don’t know much about. I hope it might be of some use.

bookmark_borderThe Drugs Work

Posted on

On Monday evening we got home to a slightly limping cat. He had a sore paw which we really didn’t want us to touch, and was generally moping about feeling sorry for himself. He seemed a bit better yesterday morning so we left him to it and went to work.

However when we got home last night he was limping heavily and his paw and leg were starting to look swollen so it was off to the emergency vet where he got a couple of injections, an anti-biotic to fight any infection and an anti-inflammatory to help with the pain and keep the swelling down.

He was a bit groggy when we got home so we pulled his bed into the living room, and put his food within easy reach. He had a wee nibble at some of his food and then fell asleep.

We were told to try and keep him calm and not let him go out for the night, which wasn’t a big issue as he ended up sleeping through until morning. He will be back at the vet later today, but he was up and about without much of a limp this morning.

bookmark_borderInstructions and ethics

Posted on

Two things are currently making me GRRRRRRRR quite a bit. One is a minor annoyance that crops up frequently, the other a fairly fundamental gripe with a certain profession.

In reverse order then, my main gripe is with the current batch of moaning politicians who are saying that it isn’t fair that they are having to pay back monies claimed because the rules have been changed and … well it’s just not fair. Cue stomping of feet and many huffing noises (no, not that kind of huffing), like the spoilt children they are.

Now, don’t get me wrong, it is slightly unfair to change the rules NOW and apply them retrospectively. I get that. The thing is, regardless of any rules, if we are all honest we’ve all broken a few rules in our time and WE KNOW WE ARE DOING IT.

So whilst they may have been able to claim for redecorating their kitchen in this seasons fashion, or getting that custom bookcase built to store their precious historical parchments, deep down they must’ve known they were taking the piss.

If they didn’t then it’s worse still, they are completely immoral.

So, yes changing the rules isn’t fair, and whilst I might try and claim a few extra pounds for a taxi ride here and there (on my yearly trip outside of the office), I wouldn’t think “you know what, it’d be much quicker to hire a helicopter, so I’ll do that” and presume that that was ok.

My company, like most, will pay for your dinner if you are away on business. I COULD order caviar, lobster, the finest champagne and finish off with half a bottle of exclusive brandy. I don’t though because that’s just taking the piss. Yes there are other reasons, ones I would like to see reflected back on to the way politicians expense claims work, such as having the knowledge that ultimately I’m spending my own money (the company pays me after all), but ultimately I am presumed to be professional about these things.

Shame we can’t say the same for our politicians.

Ohh and that other thing? Well it’s about places listing ADDRESSES on their website but forgetting that I don’t know what the building is like, nor the fact it’s one door with unclear signage above it. A photo of the premises would help LOADS!

Phew. That feels better.

bookmark_borderInterlude

Posted on

His footsteps tread heavy on this path, twigs crackle and splinter under him as he wearily walks on. He surveys the land around him, the sunlight playing through the trees as the last remnants of life wither and die in the early winter air.

He has always enjoyed these walks, the solitude revealing more to him than any conversation or sound, his emotions raw and real, unfettered by implication, speak to him in a clear voice, offering a clarity he knows is false but enjoys all the same.

His steady pace never falters whilst his eyes cast around catching movement in the undergrowth, a flickering shadow here, a gently bending stalk there. Tiny moments of life that continue regardless, and again he is reminded of the future and his dreams rush back to meet his reality. He walks on through the wood, past places he has visited before, knowing that he will soon find something new.

He takes a fork in the path, making his decision and wonders where it will take him. The air changes around him, a gentle breeze carries the chill of the sea.

Elsewhere she is drowning, clawing at the surface with her fingers, desparately casting around for something, anything, to stop her going under. Her fingers brush something only to push it out of reach, but she is in luck and the tide brings it back, a dark looming shadow above her and as she reaches up she swears it reaches down for her, pulling her up until her head is clear of the water and her gasping lungs gorge themselves on the night air.

She clinges to the log as best she can, slipping on the slimy surface until day breaks, and the warm sun helps her grip tighter and tighter until she can start to haul herself from the dark water, head and shoulders first, until soon she is sitting on the log, floating high. She throws her head back to feel the warmth of the sun on her face, and a smile slowly emerges.

Her feet dangle in the water, aware of the current beneath, feeling it’s pull and drag, the old familiarity. She resists, and watches the soft pulls of cloud slowly pass overhead as a gull floats high above, cartwheeling elegantly through the sky as it watches the world slowly spin below.

Posted in UncategorizedTagged