Month: September 2008

LOST & FOUND

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.

Part of the product

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?

Autumn Muse

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.

UA Conference – Takeaway Thoughts

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.

No read-ey, no write-y!

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.

UA Conference Notes – Day 2

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.

Obligatory Busyness post

As we head for another product release it is only fair that I warn you that I am stooooopidly busy over the next three weeks, and not just at work.

I’ve been lucky enough to bag some web design work and have just gotten off the phone with yet another person asking for some of my time in a consultancy type role. Not quite sure when I’ll fit that in but time is money and all that, although I will need to figure out my hourly rate… perhaps if I extrapolate back from the last item of gadget lust and aim for that??

Of course, as I’ve said numerous times before, I quite enjoy being busy as it usually “raises my game” meaning I tend to write more often and get a lot of other things done along the way. However I will take the opportunity to confirm that I will not be starting to write a novel (or even a novella), despite the not too subtle hints dropped by my dear mother, which recently included a free “How to write a novel” handout that she found in the Guardian.

Hang on, since when did my mother start reading the Guardian?

UA Conference Notes – Day 1

Notes and thoughts from Day 1 of the User Assistance Conference

Session 1 – Tony Self – Emerging Help Delivery Technologies
It’s been quite a while since I heard Tony speak but as ever he provided an entertaining, if somewhat limited, presentation. Covering the various types of help viewing technologies he nicely summarised some of the available choices including the features to look out for, including the ability to wrap up an online help system in its own application (using technology like Adobe AIR). It was interesting to hear some Web 2.0 features making their way into online help technologies, including voting and commenting facilities which would give you direct feedback from the people using your help system.

Session 2 – Joe Welinske – Write Mote, Write Less
Embracing the Value of Crafted Words and Images
Another regular speaker and Joe was certainly fired up, challenging us all from the outset of his presentation to consider how we work in far more detail than we currently do. First up he suggests that we should be writing fewer words whilst making sure those words are correct and so lessen the impact on the reader, providing just the information they need and nothing more.

And then he hit on something that I’ve previously mentioned here (although Joe nailed it much better than I did), namely allocating writing resource to the highest priority pieces of documentation work, rather than the traditional approach of documenting everything. It’s a simple approach that, when combined with better writing, leads the craft of technical communications to provide much higher value to the business which is good news for all of us.

Session 3 – Sonia Fuga – DITA & WordPress Solution for Flexible User Assistance
A showcase style presentation of a stunningly simple concept. With a little bit of coding work (building a DITA importer to get XML content into the WordPress database), the team at Northgate offer a web-based help system which allows users to add their own notes and to vote for useful information, and which is can receive updates with new content with each release.

How? By using WordPress features. Notes are left as comments, votes are left using a WordPress plugin, and the updateable content is controlled by only allowing the customer (who has access to the WordPress admin screen) to create Pages, leaving the Posts controlled by Northgate. I use WordPress for this website, and spoke to Sonia in the evening to confirm some of the finer details. It’s a very clever use of WordPress, and I hope Northgate release their DITA importer to the open source community!

Session 4 – Question and Rants
A short session with four speakers each giving a two minute ‘rant’ and then taking questions. Nothing particularly noteworthy came of this but it’s a good addition to the usual style of presentations and made for a little bit of light relief.

Session 5 – Dave Gash – True Separation of Content, Format, Structure and Behaviour
Another familiar name, Dave is always entertaining and a very dynamic speaker and in this session he even managed to make the somewhat mundane topics of HTML, CSS, and JavaScript interesting!

Outlining some basic principles he showed how you could take an HTML file, full of embedded behaviours (javascript), style rules (CSS), and content and strip out all four parts into a more manageable set of files. This way, holding the style and behaviours in referenced files, you can make changes to either and have them ‘ripple’ through all of your deliverable.

Admittedly this was all done by hand but the basic principles are something that you should be following if you have that kind of output.

Session 6 – Matthew Ellison – User-centred Design of Context-sensitive Help
Interesting presentation by Matthew which started a little slowly, covering the history of context-sensitive help before taking us onto the idea of task support clusters. Originally presented by Michael Hughes at the WritersUA conference, the premise is to offer the user a smarter landing page, referred to as Keystone Concept topics here.

The key to a successful Keystone Concept topic is not to limit what is presented, and to consider that it should be different depending on the context from which it was launched, with the ultimate aim of getting the user back on task as quickly as possible. This includes any form of tips and hints, and crucially suggests NOT to include the obvious stuff (don’t answer questions that users will never have!). This mirrors part of the theme from Joe’s talk early in the day, and certainly seems to be a sensible goal given the business (time and resource) pressures we are all under.

After that, I had a few beers and a chat with some other delegates, and as ever it was great to hear that most of us have similar issues, problems and solutions.

I’ll post my notes from Day 2 of the conference tomorrow.

Miscellany

Since getting my iPhone I’ve tweaked my working practises a little but, thankfully, not a lot. As most of the applications I use for my daily life (email, RSS reading, that kind of thing) are well served on the iPhone it’s been a painless transition and it’s great to have everything working, sync’d up and serving ME (unlike my previous phone which I spent far too many hours wrestling with). One thing that it has improved is my use of list/task (To Do style) based applications.

I’ve never really found an application I was comfortable with but, since shifting the rest of my productivity based activities to the web and with the iPhone providing an excellent platform for such things, I’ve been trying out a few other list applications and finally I’ve settled on Zenbe. Why? Because you can sync between the website and the iPhone app, giving me something akin to GMail and Google Reader. It’s working well for me so far.

That aside, I’m currently working on some web design with two websites in mind. The priority work is for a client but whilst I’m in the mood I’m jotting down ideas for another website as well.

Mind you I’m still a little amazed that we are heading towards the end of September and, looking ahead at the calendar, I’m pretty busy right the way through October and early November with a variety of nights out, family events and gigs (Elbow, Aimee Mann and Sigur Ros) to attend by which time, dare I say it, Christmas will be the main consideration. Erk!

Still, I’m finally able to start jogging with jogScotland again, kicking off the usual 10 week block on the 1st October and I have to say I’m quite excited by the prospect of getting back out there again on a regular basis and getting a basic level of fitness back, something which will help me in other areas of my life as well.

UA Conference – Day 1

I’ll write up my thoughts in more detail but suffice to say that, as per usual, my mind is racing with a million on one possibilities. Conferences are a good thing, even if you aren’t a position to change things it’s good to talk to other people in your profession, to find out that most of your problems are things they are experiencing as well and that there are always new ideas coming along.

Stand out sessions today were from Joe Welinske and Sonia Fuga. The former touched on some ideas we have already discussed at my workplace (the idea of focussing our efforts on the key topics, to the detriment of others – aka not documenting EVERYTHING), the latter because it’s a very smart use of existing technology, taking some simple ideas and making something very powerful. Clever stuff all round.

As I said, I’ll write up my notes from the entire conference over the weekend, but just wanted to capture the current “conference buzz” I have, although I hope it dies down soon as I need to get some sleep!

Ohh and finally a quick hello to those of you who are visiting after spotting this humble blog mentioned in the Cherryleaf newsletter. Hello!