If there is one phrase which should set off alarms in the mind of a technical writer it’s when a developer says “Ohhh but they wouldn’t use it like that…”.

Because, as I’m sure you all know, they will.

I am currently working with a few people to try and pull together a solid set of product usage recommendations. We provide an SDK and a feature rich application built using our own technology, and that application is extended and configured for specific uses. There are plenty of hook points in there and, for the most part, usage follows accepted patterns. However there is always the time when a certain component is bent and twisted and used in a way we hadn’t expected and it’s these instances that we are trying to understand and capture.

We get a view of them by exploring edge cases when testing, but it occurred to me that there is still one thing that can catch us out. Our old nemesis, ‘presumption’ (which is usually coupled with it’s friend ‘common sense’).

So now I’m on red alert for any statements which are based on presumption. Sometimes they are right, but it’s the times when they are wrong that we need to explore them, capture them and help our customers by giving them some frame of acceptable usage. It’s not an exact science, but even just pausing to have those short conversations seems to be helping.

(note to self: stop with the jokey bad grammar, peoples might think you cant be writing good)

I’ll say this quietly because I’m a little apprehensive but, for the next few months, it looks like we will have extra resource in our team. Basically we are ahead of the curve when it comes to recruiting so, until the rest of the R&D team catches up, we are one technical writer up!

Which means that we are taking the opportunity to both get ahead with some things, and catch up on others, and one of the things we’ve never tried here is to have a formal editoral review of the content. Peer review is one thing and whilst the technical content we produce is excellent, the differing writing styles and approaches each writer has does show through.

I’ll be the first to admit that I’m not all that bothered by this, simple business reasoning dictated that we concentrate on improving the accuracy and timeliness of the documentation and so, now we have done that, we can turn our attentions to other areas including findability and clarity.

The latter finds me taking on the role of Editor (I want to write Editor-in-chief just to conjure up images of a smoke filled newspaper office in the 50s), casting an eye over all of the content we produce and using our lightweight Writing Style Guide to prod and cajole the content towards something that, without being too restrictive, has a level of consistency for the reader.

As we haven’t had anyone performing that role before, it’s taking a bit of adjustment and the jokes about the “red pen” are already flying. Thankfully I work with smart people and it’s not taken long to see the results come to fruition.

What we need to figure out is how we change this model in the future so that we can all consistently edit each other’s work, lest I become a bottleneck in this process.

I’m currently pushing a business case to allow me to hire a new member for our team. The premise is that, particularly with our product set, there will always be areas of technical content that need writing but that with an additional member we can start to create other forms of content.

Which begs the question, what other forms of content can we create?

One thing I would like to get my team more involved with, both to give them a wider view of the product and to help the rest of the R&D team better understand why we build what we build, is in the creation of our Business Requirement Documents (BRDs). These documents drive the product features, setting out the requirements for the new features that we want to add for the next release cycle.

Early on in my career I remember reading (somewhere) that the technical writing team are user adovocates and that we are “the interface to the interface”. With that in mind, we need to understand both why a feature is in the product and how we expect it to be used (or at the very least, how we would like people to use it). By getting involved earlier in the product lifecycle, helping to understand and articulate the business requirements at the start of a release, we can be better placed to act in the best interests of the customer.

Being part of the team that collates and creates the BRDs will place us bang in the middle at the start of a stream of work and, by nature, we are also there at the very end, checking our documentation as the final stages of the release tweak and refine the functionality. My hope is that this end to end view of the product will help both the technical writers, and the development teams in which they are embedded.

Are you involved with early development documentation? If so I’d love to hear your thoughts on this.

Back from Spain, lightly roasted and still not quite up to speed with a working day (what, no siesta?!).

As I normally do, I reviewed the list of actions I jotted down before I left and looked over some of the last bits of work I completed, just to make sure I had been focussing on work and not been too distracted in the run up to the holiday.

One thing that leapt out at me was how I still, all these years later, struggle with consistency. It isn’t something that comes naturally to me and, truth be told, I’ve still to find a working system that helps.

It’s all well and good relying on Style Guides and whatnot but until I can make myself write consistently it’s always going to be something I need to consider. It’s not a huge problem, I am talking about a very fine level of detail here, but it does irk.

Aside from that, the usual hurtle towards the finishing line is well under way and by the end of the month we will see where things stand and what things we need to tackle next. All part and parcel of software development and, even though it’s a high stress time, I did kinda miss the buzz whilst I was away.

Recently, Ben Minson stated that “Good Enough” Really Isn’t. It’s an interesting post, and I wanted to expand on the comment I left on his blog.

Ben suggests that:

If I find myself thinking “It’s good enough” on a regular basis, I—and my users—am probably not getting all that’s possible out of my work

Before I go any further, perhaps we need to clarify what “good enough” means?

My fear is that many people take “good enough” to mean, “yeah, I’m done with that and it’ll have to be good enough”. If that is the case then yes, you are selling your users, and yourself, short. However there is a perfectly valid scenario around which the phrase “good enough” could, and should, be used.

There is a classic business situation that drives the use of the phrase, it is one with which we are all familiar and which will never ever change, and that is the age old issue of high quality deliverables versus cost of delivery. It is sometimes stated in terms of Return On Investment but the bottom line is that, at a certain point, regardless of your deliverable, there comes a point where the amount you are spending on something has reached the maximum value you can expect to gain.

Finding the balance of that will, without doubt, mean that you disappoint some users. The Pareto principle is typically offered as a rule of thumb at this point (wrongly as it happens) with the presumption that “good enough” means meeting the needs of 80% of your audience, knowing that 20% will not be as well served. The reality probably that 20% of your documentation will be used but that’s for another blog post.

Ultimately whilst we would all love to provide better information, both in quantity and quality, projects have deadlines, budgets have limits and it is there we find the true definition of “good enough”. It’s up to us, as professionals, to make the most of these situations so that when we say something is “good enough”, we mean exactly that.

To my American colleagues, who recently celebrated the 50th anniversary of their much used Strunk & White style guide, may I gently prod you in the direction of this article by Geoffrey Pullum of the Language Log.

I’ve seen Professor Pullum speak, hilariously, about english grammar and whilst I’m certain that he could find many issues with the content I publish here, I’m certain he would never be nasty or vindictive in his comments. However, in this post, in which he responds to some of the people who have commented about his article, he proves that he has the wit and style to handle such things. Both are well worth a read, even if you don’t agree with his point of view.

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.