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.

Ever get the feeling that no-one reads your documentation? It’s a frequent issue amongst Technical Writers and the general stance reflects the approach many take to make sure that, when someone finally picks up the documentation, they can get to the information they need as quickly as possible.

Given that, there is little worse than to have errors reported in your documentation. After all, if they’ve only just started using it to help them solve a problem and one of the first things they spot is an error then it’s understandable that confidence drops and that they are less likely to go to the documentation in the future.

Of course we all do the very best job we can, yet the fact remains that mistakes happen, errors occur. The reason that this tends to be a bigger issue for information is down to how we process the knowledge we have.

Without getting into too much detail, learning is a continuous process and most of that happens when you are doing things, using the tools at your disposal and figuring out how they work and how they help you achieve what you are trying to complete. By the time you decide to check the documentation, you’ve (usually) got a good bank of knowledge already, and it’s building all the time.

So, when the documentation is wrong (regardless of whether the reader spots the mistake immediately or only realises it after trying out the instructions) it seems to be an obvious mistake. After all, if I can figure out how to do X, why is the documentation wrong for Y, it’s just the same process?

Software applications that have minor errors in them are tolerated because they are the tool and sometimes there isn’t an alternative. You learn how to accomodate those errors in the application and work around them. You can’t do that with documentation, it’s either right or wrong (ambiguous documentation is presumed wrong) so confidence in the rest of the information is linked to those initial few instances of usage.

We all have review procedures that should capture errors in the documentation, we do our best to think about how the user will be interacting with the product and base the structure and content of our documentation on that information, and we all receive that email that says “On page XY of the User Guide, it states that…” and our hearts drop a little.

However I think we should embrace those moments, be positive about them! You have a user who cares enough about the documentation to complain and I think it’s worthwhile thanking them for pointing out the error, tell them that it will get fixed, and encourage them to continue to let you know if they spot anything else.

So next time you get one of those emails, or a bug in the documentation is raised, be sure to follow up with the user and thank them. They are proving that people do RTFM.

I spent most of the weekend laying, re-laying, cutting and swearing at laminate flooring. I read the provided instructions, measured twice (hell, four or five times in most cases) but still it proved problematic. I re-read the instructions, googled a little and then, after some experimentation finally figured out what the problem was… me.

Well not just me, but my interpretation of the instructions which were a little vague in one key area. Namely, where to start. This is crucial as, most laminate flooring needs to be laid the correct way to make it possible to snap all the pieces into place. It’s a one-directional jigsaw puzzle, if you will.

The details here aren’t important, but what it taught me (for the umpteenth time I guess) is that documentation needs to be complete, unambiguous and for hardware related matters at least, a picture tells a thousand stories.

I keep going back to the assumed knowledge angle, and it rings true for this example. One of the forums I found during a frantic Googling session yielded a comment along the lines of: “The professionals know this but it’s not something you’ll find in the instructions”.

I have been guilty of this in the past. Presumption is the silent virus that can kill an otherwise excellent piece of documentation stone dead. All it takes is one presumption to render an entire document AND THE PRODUCT IT IS SUPPORTING, next to useless (or at the very least “problematic”). Introducing that kind of negative thinking at an early stage of the product lifecycle makes it very hard to undo.

Although that, itself, is a presumption. I’m presuming that most people only read the documentation when they are still novice users. So maybe that is another presumption that I need to work on removing.