Category: Work

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.

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.

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.

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!

Later on this week I’ll be attending the UA Conference in Edinburgh. Formally known as the “Online Help Conference” it’s a long running conference which I last attended back in 2001 when it was held in Copenhagen. That conference involved a dinner cruise on the canals of the city, followed by a couple… ok several.. ok ok.. far too many beers, which culminated in my missing the opening session the next day (the shame!).

So, whilst it’s probably just as well I’m not staying over at this conference, it is likely I’ll partake of a beer or two.

Casting my eye down the list of speakers I’ve spotted some familiar names – Joe Welinske, Tony Self, Matthew Ellison, Dave Gash – and one name that I’m hoping to get to meet, Leisa Reichelt, whose blog I’ve been following for quite a while now. I’m wondering who else I’ll bump into? I’ve already arranged to catch up with an old colleague, and by old I mean a colleague from several years ago not a colleague who is old (sorry Sally!), and will be keeping my eyes open for any other names or faces that I recognise (I’m presuming that Ellis will be there).

Of course, as with any conference, there are a few sessions that have caught my eye as they mirror some of the things my team are currently heading towards, but I’m not sure I’ll be attending all the sessions so there will be plenty of chance to do some networking (I’m still not completely sure what that means, I tend to just go and talk to people, is that the same thing?).

So don’t be alarmed if a large Scotsman introduces himself to you, conversely if you spot me in the bar on Thursday evening (before everyone disappears off to dinner) then come and say hi (my mugshot can be found on my LinkedIn profile, see I’m not THAT scary).

And remember, mine’s a Guinness!

Most of my experience is based around software documentation. Whilst there are several levels to this, from task oriented User Guides through to highly technical API/SDK documentation, they tend to follow similar patterns making it easy for me to take my experience and apply it to new challenges.

I’ve also been involved in writing up procedures and guidelines as part of an ISO quality system, a little whitepaper style writing, and even the odd product brochure. All of which require a slightly different approach but the same grounding in the basics of understanding the audience.

However I’m aware that there are many other forms of technical writing, and I’m curious to find out what everyone else does? Do you write documentation for hardware products? Do you write proposals? Procedures?

Ultimately I’m starting to look at other areas of our profession to see if there are any good things that I can re-use where I am. If you have a moment, I’d love to hear what your main writing focus is, let me know in the comments.