Month: September 2008

bookmark_borderLOST & FOUND

Posted on

It appears I have lost my words. I’m sure I’ve just left them somewhere, carelessly abandoned without thought. I’m sure I shouldn’t really panic too much, knowing they’ll turn up like an odd sock at the bottom of the wash basket, and I’m certain that it is probably a good thing they’ve chosen this moment to go missing.

Why?

Simply because there is everything and nothing to tell here. As usual. Too busy you see, too busy to hunt for the words myself so I’ll presume they are where I left them, even though I can’t recall where that is.

So excuse me for a while until I find my words again, and if you do spot them roaming around please tell them to come home. Thanks.

bookmark_borderPart of the product

Posted on

Last week we held a shortened Kaizen-style event in which we discussed the requirements capture part of our product lifecycle. It was an interesting couple of days which yielded a new process that we think is an improvement on the previous one. That makes it sound very simple, it certainly wasn’t, but it was a fascinating couple of days.

As I’m responsible for the technical information that comes out of the development group, I had a slightly different view of things and took away some ideas to discuss with my team of writers. One of which we have discussed a little but haven’t yet pushed too hard. I think that is about to change.

Going back to our requirements capture process, one part of the new process suggested some additional information that should be provided with the business case attached to a requirement. That got me thinking.

At present we (my team) face a backlog of information which was never previously considered nor written up (an oversight by my predecessors) and we’ve been trying to tackle the backlog as well as keep apace of the new features being added. Ultimately this has proved futile and we’ve discussed ways to get around this. More resource is one option, but another would be to work smarter and only provide documentation based on a priority basis or, for want of a better description, based on a viable business case.

The question I’m pondering is whether we go the whole hog and make documentation requests part of the requirements capture process, or use our own understanding and knowledge of what is required and build our own business case.

It’s, hopefully, a fairly unique situation but I’d still be keen to hear how you handle incoming requests for documentation?

bookmark_borderAutumn Muse

Posted on

The once billowing grass is gone, shorn from existence, ripped from green to dirt by savage machinery. Under dripping trees at the edge of the field stands the farmer, admiring the close crop of the land as it ripples towards the horizon across the furrows of once turned soil.

Standing at the top of the hill he turns from the chilled air sweeping through the valley to survey the rest of his land. An oddly shaped patchwork this, bordered by stone and scrub as it climbs and slides across the terrain. The cool breeze dances on stalks and leaves, the beginnings of autumn burning spots of gold and red, glimpses of light through dense trees herald another cycle as the leaves slowly start their long tumble to the ground.

…

And that’s it, that’s all I’ve got. I have no story, no characters, no plot devices, no he said she said. No pace, no direction, no structure nor prose. I am mute until inspiration returns, until the muse once more lands gently on my shoulder and generously bestows her charms and inspiration.

Her visits are fleetingly random, endearingly erratic and completely at her whim. You cannot depend on her to arrive and remain, and deep down as you know that to make such demands would be the end of it all so you stay your course, riding the waves as best you can.

Such is the way of things for this most complex of spectres; she is the free spirit of whimsy, the demanding guide, a strict mistress when she calls, a caring spirit when she leaves, a raging torrent and calming stream. You cannot use what she gives without permission, and cannot call on her, beckoning her to your aid. She is not under your control and needs only the slightest excuse to float away.

The mundane returns and she loosens her grip, slipping away as I type. Dust trails of inspiration whirl as she departs.

Posted in UncategorizedTagged

bookmark_borderUA Conference – Takeaway Thoughts

Posted on

Attending a conference is a mixed bag of experiences yet regardless of your knowledge in certain areas it is always a worthwhile to meet up with your peers and discuss the various common issues, gripes, moans and solutions that we all share.

I was also lucky enough to bump into some ex-colleagues and to meet some email correspondents face to face, not to mention the numerous interesting conversations I had with other delegates. Yes it’s safe to say that the value of connecting with your peers is high and entirely justified the cost of the conference.

That aside there were also a couple of subtle themes that emerged during the sessions, the main one being that to enable us to work smarter, we need to push our involvement as far upstream as possible. Joe Welinske hinted at this as a way to make sure we are working on the highest priority items, and this view was further (obviously) expounded by user experience expert Leisa Reichelt. Considering that many of the technical communication questions and considerations that crop up are frequently answered by the stock response of “know your audience”, it was a timely reminder that by pushing ourselves towards the point where we can gather product influencing information about our audience we can start to make better decisions both about WHAT to write and HOW to write it.

Other thoughts, on a random basis:

  • Can we provide our online help in a single session browser (using something like Adobe AIR?).
  • Can we leverage the Web 2.0 ideas of commenting and voting on help topics?
  • Content is THE most important thing (sometimes it’s good to be reminded of this basic fact).
  • Choosing our single source solution quickly was the right thing to do, they all have flaws so we will find them and get round them sooner rather than later.
  • Can we look to web CMS to help provide a better set of technical information?
  • The first page the user lands on is crucial, break from the traditional model and create custom landing pages containing anything and everything that helps get them back on task.
  • Is the (stereotypical) persona of a technical writer actually stacked against driving change? Is that why so many of us are stuck following best practice? (I’m presuming best practice here to be a bad thing.
  • Jakob Nielsen was quoted 4 times by different speakers – do we really need any more evidence that we need to be user experience/usability minded when writing and structuring information?
  • If possible, define a variety of contexts within which the information can appear (version, product, country, etc) and use initial custom searches to provide a sensible landing page.
  • There are MANY lessons to be learned from websites, most of which have Information Architects and UX Designers, something we don’t typically have access to.
  • Users don’t care what kind of information they get as long as it answers their question.

Overall it was an excellent conference, and it was great to hear some of the things I’ve seen discussed in various blogs being brought to a larger audience. Definitely one to attend next year.

—

I’m not the only one that enjoyed the conference, Ellis rounds up his thoughts over at the Cherryleaf Blog.

bookmark_borderNo read-ey, no write-y!

Posted on

Dearest Reader,

(Yes, that’s you)

I’ll keep this as simple as I can.

In my previous post I stated, quite clearly, that I would be taking “the opportunity to confirm that I will not be starting to write a novel (or even a novella)”. I realise my mixing of positive and negative actions in the same sentence may have confused your simple mind, for that I am sorry. I am certain you already have enough difficulty and confusion in your life and I apologise for rendering your simple mind asunder with my badly crafted sentence.

I realise my education places me at an advantage, how quickly it is that I forget that not everyone can read whilst sitting on the loo, I can skim through a magazine in no time, picking out all the best bits with ease. I occasionally read the words too. Yes I should remember that you may not be as smart as I, and that not only do you have to remember how to tie your shoelaces every morning but that it takes you several minutes beyond that to realise that you are wearing slip-ons.

So please let me clarify my statement, and allow me to re-iterate for those of you who apparently cannot read. The statement I made is thus, clearly and unequivocally, I AM NOT GOING TO WRITE A NOVEL (OR EVEN A NOVELLA).

WILL NOT.

CAN’T MAKE ME!

I’m ashamed to admit that even my own parents (who are teachers for godssake!!) failed to properly read that announcement and continue to encourage me to do something I have stated, repeatedly, that I am not interested in doing. These are the types of parents you see in documentaries on Channel 5, and if I let them have their own way they’d no doubt have me attending some horrid pageant for 30-something sons, reciting my own paltry and pathetic attempts at poetry.

You may now be considering pointing an accusatory finger in my general direction, so I will concede that, maybe, perhaps, I could have emphasised my point a little better but the underlying lesson that I will take from this sorry debacle is that my faith in you (yes YOU) dear reader has been mis-guided. I have been presuming all along that you can read and, alas, it seems you cannot.

It makes me wonder what the hell you’ve been commenting on these past nine years, if you’ve been unable to properly parse and process the eloquently crafted prose laid before you. What kind of imbecile are you?

This entire sorrry episode convinces me that I am correct (I usually am) and so I will be sticking to my aforementioned, and since clarified, announcement which I shall repeat here in one final attempt to get the message across.

I AM NOT AND WILL NOT BE WRITING A NOVEL (OR EVEN A NOVELLA).

After all, if you lot can’t even be bothered to read things on my blog properly, why the hell should I write a bloody book!

Yours condescendingly,

Gordon

P.S. There are several grammatical and spelling errors throughout this post, but I’m not expecting you heathens to spot them.

bookmark_borderUA Conference Notes – Day 2

Posted on

Notes and thoughts from Day 2 of the User Assistance Conference

Session 1 – Juliette Fleming – XML Tagging and Search Facets
An early start for an interesting session in which Juliette outlined how Oracle have introduced search Facets to their online help system. Essentially a facet is a tagged chunk of information or help topic, and their help system has been coded to make the most of these by using the tags to decide in which context the help topic should be used.

This allows their help system to display information, for example, for a given product version, language, product and topic type when the user clicks to get help from the application. The facets are also used to present, essentially, pre-populated searches as a starting point (or Keystone Concept, perhaps) for the context-sensitive help. A smart idea.

Session 2 – Tony Self – Implementing Collaborative Authoring with Wikis
I didn’t attend this session but heard it was a good introduction to the topic for beginners. Having presented on this topic myself I figured it was safe to take some time out.

Session 3 – Rachel Potts and Brian Harris – Delivering Help in a Support Portal
An entertaining presentation on a topic that matches some of my thoughts of where my team and I should be heading. The core problem that Red Gate had was to tie together the myriad of information sources into a cohesive whole as they figured that their users didn’t care where or how they got the information they needed, even though Red Gate offered many distinct to try and guide them to a particular type of information.

With a little effort they came up with a solution which included restyling some of the existing information, and taking a new direction for the online help, recognising that most of their users would look for Support rather than Help (acknowledging that most people don’t like to admit they need ‘help’!). Shifting to Author-it for their technical writing team, they post-process the output to provide better metadata which enables the search engine and supporting presentation framework components to offer the best information at the best time.

As we are moving to Author-it it was very interesting but I was a little disappointed to find out (when chatting to Rachel and Brian later on) that they are ditching Author-it because, when creating new versions of topics, you lose the associated metadata. I’m hoping that’s just a bug that has yet to be fixed and will be checking that with Author-it very soon.

Session 3 – Dave Gash – Introduction to XSL Transforms
Following on from his presentation the day before, Dave suggested that this would be an easy to follow session on a fairly simple topic (even though it can end up being very complex to pull together).

However, having dabbled with XSLT myself I decided to sit this one out and spent some time chatting to some of the vendors.

Session 4 – Leisa Reichelt – Practical User Research
Having been an avid reader of disambiguity.com, where Leisa blogs on User Experience topics, and as it wasn’t directly a technical writing focussed presentation, I was looking forward to this presentation. Leisa’s style and delivery kept it interesting and informative, and seemed to be very well received.

Taking the role as a user advocate is a common one for a technical writer, and a lot of what Leisa was discussing was simply taking that a step further. She offered some suggestions on how to capture better user information as well as offering some simple reasoning that shows you can do useful research with a small set of subjects, and a simple model that shows that, without all the correct design processes in place “changing buttons on a user interface is like shuffling chairs on the titanic”.

As I’ve mentioned here on this blog, I’m a big fan of technical writers pushing (or encroaching?) into other areas. For many smaller companies without the budget to hire a dedicated usability professional it’s good to know that even a small effort in this area can make a difference, and that effort will mean a better understanding of your audience which is always a good thing.

Session 5 – Matthew Ellison – Creating Table Styles in CSS
Again, another session I skipped largely because I’m quite comfortable styling with CSS and a quick google suggests similar information is widely available online.

Session 6 – Prof. Geoffrey K Pullum – Far from the Madding Gerund
I have to admit that it was with a wary head that I took my seat for the closing session of the conference. I’ll happily admit (and lord knows there is plenty of proof right here in this blog) that whilst my writing is acceptable the finer points of grammar are occasionally ignored, so the thought of listening to a grammarian waffle on about deontic modality or ditransitive verbs didn’t exactly thrill me.

So it was with some humility and shame that I apologies to Professor Pullum as his talk was fascinating, funny and hugely enjoyable. Seating his advice in examples, and several quotes from The Importance of Being Earnest, he assured as all that our writing was perfectly acceptable and that we should ignore people who seek to enforce arcane and just plain wrong grammar rules. Split your infinitives if you must, dangling your modifiers and feel free to end that sentence with a preposition if you feel the sentence warrants it.

Ultimately, Prof. Pullum assured us, we are all professionals and the way we write is accurate for the audience. That and the fact that a lot of grammatical advice is complete nonsense.

If you get the chance to hear him speak, do so. Even if only to hear his range of accents, all of which are executed so well I have to wonder if he spends some time practising them.