Tag: UA

bookmark_borderOn pedantry

Posted on

I start this blog post with an admission and an apology.

Admission: I am a manager, I don’t spend a lot (any) of my time writing technical content these days.

Apology: One of my weakest areas is in the intricacies and ‘correctness’ of grammar. *

That said, there is one thing that continues to frustrate me about the technical communications profession, the constant ‘deep dive’ into every single aspect of one sentence, one clause. Dear grammar pedants, please stop!

Don’t get me wrong, I know that good written information is a keystone of our profession and I’m all for discussions to make sure things are being approached correctly and debated thoroughly, where appropriate.

Please note the last two words of the last sentence, “where appropriate”.

Maybe it’s just me, but as each of us write for a specific audience, likely to a specific style guide, such discussions become academic almost from the get go. What really irks is when discussions on other aspects of our profession are diverted towards this area. For example, “Content Strategy is important! … Yes, but ultimately the paragraph that someone reads once they have found it needs to be written in the active voice and never ever punctuate that bulleted list with commas… ”

And so on.

I’ve seen it so many times I’ve started using it as a guide. When any online discussion that isn’t explicitly about grammar and punctuation, whether forum or mailing list, reaches the point that someone reaches for the grammar gun, I stop reading, I disengage.

A few years ago, when the UA conference reached Edinburgh in 2008, one of the sessions was by Professor Geoffrey K. Pullum, a noted linguist. It was the closing session and I approached it with some dread, a presentation on language would surely be all about the use of transitive verbs and the perils of infinitives which are split. How wrong I was, leaving the room at the end with a simple, repeated message.

Write as you speak. Write as if you were explaining something to someone sitting next to you, put aside the rules of grammar if needs be!

I blame my current stance, my dislike of long academic discussions on someone who, I’m sure, has initiated and partaken of many such discussions himself.

Forgive me if I’ve offend anyone, I’m not saying that correct grammar is a bad thing, far from it, I just think that in the current day and age we, as a profession, need to raise our view and focus on bigger things. The language will take care of itself, one way or another, let it go!

We should be looking to influence, to sell, to push ourselves to the forefront of our companies as the experts we are in that valuable (and its stock continues to rise) commodity, information.

 

* Yes, there are deliberate mistakes in this post. Feel free to point them out in the comments.

bookmark_borderConference chatter

Posted on

“The time has come,” the Walrus said, “To talk of many things…”

It’s that time of year again, with the UA Conference currently underway (see what people are saying about it on Twitter) and the Technical Communication UK conference just around the corner.

We are lucky enough to be able to get to such events, even though we still need to pick and choose due to budget constraints and, once again, the multi-stream approach of TCUK makes it easier to justify. Looking at the programme for this year, there are always two sessions of interest, sometimes three.

As ever, and this is something I’ve commented on before, the benefits of attending conferences go above and beyond attendance at the sessions. The conversations over lunch, or dinner, or over a quick coffee between sessions make all the difference. Being able to bounce ideas off fellow professionals from different companies (working in different industries) gives you some unique views and solutions which you would struggle to get otherwise.

Add in the additional interaction via Twitter and conferences can become a mind-bogglingly fast-paced solution centre!

Of course implementing those solutions is a different challenge but I’ve yet to come away from a conference NOT feeling energised and ready to tackle things and, again, social media then helps extend those conversations.

Creating the business case for attending a conference is usually centred around the sessions, and what the value and benefits of attending will be to the company, but I think it’s also worth factoring in the availability of your peers as part of that discussion.

bookmark_borderLanding Pads

Posted on

Helicopter landing pad


I’m guessing that you don’t want to miss that landing pad because if you do you’ll end up ditched in the ocean, floating around aimlessly and with no real idea of what to do next. Can you imagine how horrifying it would be if that happened? Floating there, unable to get back to land and with who knows what swimming around underneath you…

Yet this is the predicament that many users of online help find themselves in, having strayed into the online help they have been cast into an ocean of information with no real idea of how to get back to shore. Ohhh sure, we tell ourselves that the there is an easy way to get to the information they want through our carefully crafted Table of Contents, or perhaps a more direct route can be navigated using that Index you toiled over for hours, or better yet if they use the Search functionality they’ll find what they want. Right?

And, ultimately, yes these mechanisms work. If you know how an Index is structured you can quite quickly navigate to a keyword that probably matches the information you are searching for and should, hopefully, take you almost directly to the very help topic you need. Same goes for the Table of Contents although they are a little more prescriptive and you need to know what you are looking for to be able to find it, and of course the Search will provide you with several help topics that are, probably, what you are looking for.

Meanwhile the sharks have gathered and are nibbling at your feet!

At the UA conference last year, Matthew Ellison gave a presentation on what he termed “Keystone Topics” and in the Summer edition of the ISTC Communicator magazine (again, chock full of good stuff, it’s worth the price of membership alone if you ask me) Paul Filby covers something similar, outlining how to provide “The perfect help-system landing page”.

And so, with all of that in mind that is my task today (yes, a Saturday).

The concept is simple enough. You create a single topic that will be displayed to the user when they bash our old friend the F1 button. That topic is unique to the help system and, based on context, can be used to display a smarter set of links to potentially useful information. If you have the means you could display the most commonly viewed topics or, as I’m doing, you can point to the start of several paths covering the most commonly used areas of the product.

I don’t expect to get ours right the first time round, but hopefully the concept will work. I’m including a small addition to the foot of each such topic, asking users to contact us if they have improvements. It’s only on the landing pages but I’m hoping it might drive a nice little cycle of innovation with direct feedback from the users driving the content of the landing pages in the future.

Hopefully the landing pages will give our users some where dry to stand and survey the land a little, with clear signs to help them get to where they want to go.

bookmark_borderHelter Skelter

Posted on

Helter Skelter

When I get to the bottom
I go back to the top of the slide
Where I stop and turn
and I go for a ride
Till I get to the bottom and I see you again!!!!

Ever get that feeling that you’ve been here before?

I write this blog post with haste as I’m halfway through the penultimate week of a particularly arduous project. Not only are we releasing a new version of the product, but we are completing the first major stage of our move to Author-it.

Overall the migration has been pretty painless. There are still some Word templates issues to work around and getting to grips with Variants has still to be tackled, but overall we are pretty happy with our choice. The only major gripe we have is partly our (ok, MY) own fault, and it’s here that I’ll offer the most valuable tip I can.

If you are migrating legacy content to Author-it (we were moving from Structured FrameMaker), make sure you thoroughly test and check the import settings. Time constraints had me rush this stage and we ended up paying for it, spending far too long cleaning up rogue topics than we had planned. Every cloud has a silver lining though, and it does mean that the documentation is now far more consistently written and styled than it had been. However, going through some 5000 odd topics by hand wasn’t the greatest use of our time!

Soon we will be looking to how we can leverage the output to provide better access to information, feeding into the developer community website we have already built, and improving how we deliver information alongwith our product set.

For the former we have taken some inspiration from the presentation by Rachel Potts and Brian Harris (Red Gate Software) at last years UA Conference, titled Delivering Help in a Support Portal. For our implementation the Publications team will take the lead, and it’ll be interesting to see where it takes us. Web 2.0, anyone?

We will also be looking to provide better online help by introducing Keystone Topics, as suggested by Matthew Ellison. Author-it should make these topics, which are the first topics the user lands on when they start the online help and which provide sensible links to common information (rather than just providing repurposed user manuals), very easy to build.

Two of the team will be in Cardiff for the conference this year so it’ll be interesting to see what we learn there and how we can really start to leverage Author-it in more and more powerful ways. I’m definitely keen to start innovating what we do and, in a few weeks time, we won’t have any further barriers to stop us.

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_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.