Just visited the McAfee website and on one of the forms encountered a, shall we say, anomaly presented itself.

I am a patriotic kind of guy, and I’m not in any way anti-American (I’m well aware that the percentage of idiots over there matches the numbers we have here), and when you actually consider what I’m about to tell you isn’t really about patriotism, jingoism or somesuch.

Rather it’s a wonderful piece of bad programming that I’ve seen before, centred around the fact that (at least for the purposes of this discussion) the country I am identified with is known as both the United Kingdom (UK) and Great Britain (GB).

I’m Scottish, and my country is part of Great Britain (which is the main island mass which also includes Wales and England). Add in Northern Ireland and you have the United Kingdom. It confuses me but that isn’t really the issue here.

When selecting my nationality in an online form, invariably I have one option: United Kingdom. On some forms I am delighted to be able to select Scotland, and on others I have to hunt for Great Britain.

However, the McAfee form in question proved a little troubling.

On highlighting the Nationality list, and tapping the U key, I was taken down to Uganda. A few more taps of the DOWN arrow key is usually all that is required to get me to “United Kingdom”. Not this time though, so I clicked the list top expand it, just to make sure I hadn’t keyed too fast but no, there was no United Kingdom.

No problem, I think, I’ll just tap the G key to get me back up the list towards Great Britain. This time I expanded the list first and scrolled down to… hang on… no Great Britain either? Great! Must be an option for Scotland!

Nope.

Somewhat puzzled now I double-checked that there was no entry for Scotland. There wasn’t. United Kingdom? Not listed amongst the rest of the nations of the world that begin with U. Must be Great Britain then?

And there it was, nestled away amongst the Gs. “United Kingdom”.

Now technically I can figure out what has happened, the label which is displayed to the user is “United Kingdom” but the value, on which the list being sorted, is set as “Great Britain”.

I have to wonder if this was tested at all and if so they have missed a fairly obvious set of test cases. If you are a global company then you need to consider these things.

OK, admittedly it is a tiny mistake amongst a large and complex website but it does serve to remind me to take the unhappy path through our own software now and then. I have a tendency to check through screens and processes presuming a lot of knowledge and taking the happy path.

Footnote: I worked for Dr. Solomons for a year before they were purchased by McAfee. One of the projects (ditched by McAfee) concerned a global company update system, during which many long design meetings centred around just this kind of “international” issue. But hey, I’m not bitter that they made me and 250-odd other people redundant almost immediately after they bought us, honest…

I started this blog to have a separate place to write about my “professional” thoughts and I guess I thought I could maybe add a little value to the cluttered world of technical communications, or at the very least raise my profile a little. Yes, I have an ego, but it’s kept in check for the most part.

However, like my other blog, the main reason this blog exists is to give me a place that I can consider and process my thoughts. I’ve always found writing things down helped me get a good sense of what they were, even if I didn’t necessarily start with a cohesive picture in mind. Sometimes the simplest issue, one that has eluded me for some time, leaps into focus when I start writing. I’m not sure if it’s always been that way or I’ve now trained myself into such a habit but I’m not complaining, it works for me and I’ll admit that I still get a little buzz when something “clicks”.

If I were in a cartoon a light-bulb would *plink* into existence above my head when that happens. Reality can be such a disappointment.

Today brought a good example of such a moment and rather than deleting my thoughts, I’d thought I’d post them here. Sharing is power after all (badly paraphrasing remains inexcusable).

One continuing theme on most of the mailing lists I follow and in various blog posts across the land, is that of knowing your audience. Knowing why you are writing, and who you are writing for are the fundamental tenets of our profession. They are so fundamental that, if I’m honest, the incessant reminders about them do start to grate somewhat. After all I’m a professional, how many times do I need to be told to consider my audience? How many times do we need to restate something we all know and understand.

I’m happy to admit that some will know more about their audience than others. Some will make do with a rough approximation of what their audience expects, whilst others will interview and analyse their customers and gather requirements and direction directly.

Regardless of your level of commitment to understanding them, anyone who is writing must (surely) consider their audience. Yet, at every turn, the answer to many questions all stem from that presumption, and are presented in simplistic terms. Know your audience they say. OK OK, I get it!

The thing is, after reading such a response for the umpteenth time it suddenly struck me that yes, we do need to be reminded of this basic fact, time and again.

We all have pressures on our work. Whether those pressures come from commitments made to others, from our own professional integrity, or directly from the customer, they all serve to focus us on the end goal and usually to start thinking in terms of quantity. We know we need to document the new interface to the ACME Widget and when pressure is exerted their is a temptation to take shortcuts, and the easiest shortcut is, by and large, to forget the audience.

The cardinal sin allows us to omit information on the presumption that they will “probably know it”, to structure the information according to UI rather than task, and ultimately to regress to a “if you can click it, document it” mentality. That may be a valid mode in certain circumstances but that will depend upon, yeah you guessed it, your audience.

Audience analysis, the use of personas, call it what you will, if you don’t have at least a rough idea of the type of person you are writing for then why bother? You won’t be structing the information correctly, you won’t be pitching the level of information appropriately, and you most certainly won’t be thinking around the various conceptual models your audience are likely to use and understand. The more you know, the better you can focus your documentation, drilling down into the tasks they need to complete and what they need to know before they begin. The better your knowledge of your audience the more likely it is you’ll produce documentation that they can use.

Put it this way, if you aren’t writing for a specific audience, who ARE you writing for?

Ooops.

I’ve gone and done exactly what I said annoyed me, lectured you all on knowing your audience when you already know that you need to know that. You know?

Next time I read yet another “Depends on your audience” response in a mailing list I’m going to try and remember that advice and apply it to my current work.

Addendum: Charles Cooper has been considering the same thing.

Having recently upgraded my MacBook to run the latest version of OSX, I’ve been using the built-in Help to figure out how to configure things to the way I like them. It’s an excellent example of well designed and integrated help. Of particular note is the effect shown in the screenshot below.

An excellent example of integrating user assistance with an in-built online help system. Don’t you think?

Typing in your question to the text box, top-right of the window, dims the contents and ’spotlights’ the items which possibly match what you are looking for. Smart, huh. There are many more examples of this kind of thing but this one caught my eye.

I’m a member of the Information Architecture Institute (IAI) but I’m still not really sure why.

I joined about a year ago, although I’d been following the website and reading articles in this area for some time before that. During that time I developed a sense that, at a fundamental level, there is a lot of crossover of knowledge and approach between practitioners of Information Architecture and those of us in the land of technical communications.

The IAI website states that:

As the information age rolls forward, our businesses, markets and societies are being transformed into adaptive, connected networks. The Internet of today only hints at the ubiquitous communication infrastructure of tomorrow. The construction of this brave new world requires a new kind of architecture, focused on digital structures of information and software rather than physical structures of bricks and mortar. As we spend more time working and playing in these shared information spaces, people will need and demand better search, navigation and collaboration systems.

Whilst a lot of the work of an IA is focussed on the web, the basic principles of good design hold true regardless of the medium. Given that many technical communicators provide online help which may, or may not, be delivered in a web format or via the web itself (as opposed to viewed locally in a web browser) those same principles can be used here. Even if we consider the production of information for print, the same considerations of information access and structure, personas and task analysis, require a level of understanding and design in which both IAs and Tech Writers specialise.

As an aside, this type of thing is one reason why you should hire a professional Technical Writer and not rely on other people in your organisation “filling the gap”. They may be able to write acceptable english, but information is next to useless if badly structured.

Looking further into the lair of an IA, we find many are now involved in what is commonly known as the “social web” (aka Web 2.0). With information being shared and promoted across many different areas, both geographical and social, the structure and usage of that information needs to be careful considered, and with more and more information sources moving from traditional outputs (print) to modern outputs (web), then the modern day technical communicator has, essentially, become what is now known as an Information Architect.

Strictly speaking it’s more another ‘hat’ for a Technical Communicator to wear but the idea is the same. As well as writing, design, illustrating, and doing everything else that is involved with creating technical documentation, now may need to consider an additional mode of usage, one which has grown rapidly in the past couple of years.

The more I learn about Information Architecture, the more parallels I find. Designing information structures, leveraging an ever increasing set of tools, is fast becoming part and parcel of our jobs (well, ok, MY job at least). Add in the fact that we are, frequently, the people populating those structures then it’s easy to see that there are many lessons we can learn from those in IA.

Related Information:

• IAI website
• Boxes and Arrows

I’ve been chasing this train of thought for a while now and decided to start writing my thoughts down in the vague hope that they come together in a way that makes sense to others. It seems to make sense to me but, as yet, there are a few grey areas into which I may stumble. So, not so much a train of thought but a car crash of ideas, if you will.

Shoddy metaphors aside, the main crux of my thinking is based in my efforts to find a central point around which I can arrange my knowledge. Obviously my knowledge of some areas is greater than my knowledge of others, but part of this exercise is to start to identify the areas in which I’m lacking and so allow me to investigate them further, to feedback into my train.. no.. car… umm, driveshaft??

OK, let’s start over.

The role of a technical writer is fairly varied, and merrily traipses through several distinct fields. Most technical writers will know a little (or a lot) about many topics, how to structure information or how to create a usable index, they will be also have some knowledge or awareness of, for example, typography and readability issues, they will have some knowledge of working with graphics, and they will also gain knowledge of the various tools they use. Suffice to say that the skill set and ‘earned’ knowledge a technical writer posseses is almost endless.

And that’s all before you consider how much they know about the products that they are documenting

So from that starting point we can see that technical writers already dip their toes into various pools of expertise.

Now, let me just changes hats for a second… right. I am now a web designer.

Look at the knowledge I have attained as a technical writer, with a web designer hat on, there are a lot of parallels. Some are direct, some not so obvious but still discretely linked, after all, regardless of the medium the two disciplines share key facets of importance; content and audience. The delivery mechanism is secondary to those at all times.

Web designers also span several different fields, with some knowledge of HTML, CSS and other languages (usually text based), they too worry about layout and typography to ensure readability is maintained, they plan what type of content will be created, and understand the need to structure that information in such a way that it is explorable. The parallels are many.

So, somewhere in my head I’m wondering why the two disciplines don’t seem to be talking to one another. Is it lack of visibility? Is it just me that thinks it is this way? Are there secret meetings going on as I speak?

One of the reasons I ask is because there is a wealth of information out there that focusses on web design, even spilling over into the social/community aspects of information sharing, which the technical writing world could use and leverage. Have a look at some of the articles on A List Apart, for example. Those which aren’t specifically about code tend to talk in terms of analysis, planning and design. All things I do as part of my job as a technical writer. Boxes and Arrows takes you into Information Architecture territory, with user experience key and, for many of us who work in software development and who can influence both the UI and the Use Cases that help constitute a software application, there is a lot of useful information that we can adapt for our own use.

Audience, audience, audience.

A simple mantra, and one which crops up in most technical writing discussions at some point. If you don’t know your audience then how do you know what to write, and why you are writing it?

Most technical writers will be aware of the particular audience for the document they are working on, but as part of understanding WHO the audience is, we must also have some knowledge of WHAT they do, or don’t, know. But how far can presumption take us? If we don’t have access to our users to perform a thorough user analysis then we are, at best, guessing. Even if it is in a very well-educated way.

Of course understanding WHY someone is using your documentation goes a fair way to providing a basic framework upon which you can base further “guesstimates” as to what information your readers require.

With this in mind, I have long since used the following general presumptions. I will stress that they are no replacement to actually talking to users, but they can help focus early discussions in a project.

My suggestion is that there are at least six key phases, or touching points, during which a customer will be interacting with your company and the information you provide. Touching points are not always direct, may not always be pushed out to the customer, and they may not always be followed in a linear fashion, as they are entirely dependant on the needs of the user.

Naturally the specific Touching Points within your interactions with customers will differ, but it’s a good exercise to step back and make sure you’ve captured them.

First Touching Point
The first time a customer hears about your company. This may be because:

• They have a pressing business need and their research brought them to your website.
• They attended a Trade Show, and received your marketing literature.
• You are following up on a potential sales lead from another project.
• They received a recommendation from a colleague.
• They have worked with you before.

The information requirement at this point is largely high level and business focussed. It’s more than likely that the information will be consumed by senior management, or perhaps used by middle-management as part of a briefing to senior management.

Second Touching Point
The customer is aware of your company and your products, and has a basic understanding of what is offered. They are looking for more information to allow them to make the necessary business decisions: Will this product meet our business need? Does this product offer a good ROI? Is our business ready to adopt this product? Does this product meet the regulatory requirements our company operates within?

The information requirement remains business rather than technically focussed, but has some aspect of product documentation available, an overview of the product capabilities and the underlying requirements and prerequisites.

Third Touching Point
By now the customer has decided that your product is viable for use within their business. You need to make sure they are fully aware of the implications of purchase, and of any additional requirements that their specific needs may drive.

They need to raise a business case and start the purchasing process.

Largely driven by Sales, the information here may be pulled from a common pool, with the prerequisites driving the information itself.

Fourth Touching Point
The customer has bought the product, and the deployment phase has begun.

For a custom solution, the bulk of the information needs to flow through a deployment or solutions team, as well as being usable by the customer throughout the lifespan of the product. This touching point is key during this stage as a lot of the information you will provide at source is likely to be edited to match customer needs. For an out of the box product, the information is centred around product functionality.

Fifth Touching Point
The product is deployed on the customer site. You are now in the support phase, and the need to be able to handle usage questions and more advanced requests for specific information.

Information requirement is largely customer driven but may still be pulled from various ad-hoc forums and FAQs.

Sixth Touching Point
The customer is transitioning from one version of your product to the next, or between products.

As a starting point, I think this approach is valid, and I’d be interested to hear if you have made similar assumptions. I wonder how often we document products without any insight into the audience whatsoever, and if you have done so, I’d love to hear how you tackled it.