I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase.

It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies.

Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online).

So why do we still maintain this view of how information should be provided?

There is a level of comfort in having a table of contents and a structure to the information available when writing technical information. It allows you to make sure all the required information is in place, but most of the research I’ve read, and most of the anecdotal evidence I’ve heard, suggests that those lovingly created table of contents are not heavily used.

The index is another area, hell it’s another profession altogether, that we spend a lot of time crafting and rightly so as it is used by many people to navigate their way through a document.

But one thing that trumps both of these methods isn’t available in printed documents but is widely available for online information. Search.

OK, so none of what I’m saying is new, or revolutionary, far from it. Those of us who have been creating online help, regardless of the format (a lot of which was before the internet was popularised), know that if there is a search option available, it will be used.

With that in mind, and this is most definitely something we will be consulting with our users about, we are toying with the idea of dumping the index and the table of contents, making sure the content has a good set of internal reference links so users (power and novice alike) can find “paths” through the information, and switching the front page to be a Google-esque search.

Luckily we can pilot this approach whilst still producing the Javahelp, PDFs and HTML (Webhelp in Author-it terms) output so we don’t completely alienate our users. It’ll be interesting to see outcome.

You know when you have a set of disparate, yet related, ideas and plans and whilst you know they WILL all tie together it can sometimes be a struggle to both see how that will happen and communicate it to your various stakeholders? Well that’s where my head has been the past couple of weeks. No wonder I’ve been tired and headachey, my brain hurts!

Basically I’m trying to pull together a plan for the next 6-12 months that wraps up the ongoing development of the single source solution my team have in place (we are using Author-it), with the production of a knowledge centre (containing all of the product documentation, releases notes and more), which will be hosted on the developer community website I have setup, making sure we can provide partner friendly information all the while ensuring that we are covering all the levels of content required.

That, plus a few other side projects.

I have a mindmap of all this, and whilst I’m not fond of them it is allowing me to make sure I’m covering all the required areas.

The good thing is that it is all starting to come together so all I’m really doing is tweaking the timescales and goals a little to make sure they all align. The downside is that it’s generating even more work for me and my team which, as it happens, is actually a good thing.

It’s safe to say that I’m fully hooked into the Web 2.0 world. I manage my email, calendar and task list online, as well as write and share the occasional document. I blog (in three places), I twitter, and I follow a wide swathe of information via RSS feeds. If the internet disappeared overnight I’d be lost, for any time I think ‘information’ I think internet, I don’t think book, or library, or even online help. I think internet.

This is even more prevalent when I’m looking for a solution, an answer to my current burning issue. At that point I’m looking for information from my peers, from other users or anyone else who has had, and solved, a similar problem, and nine times out of ten I’ll turn to the internet to search for that information.

Whilst such answers can be hard to track down, it feels productive to be searching for the specific answer to my specific issue, even if that takes some time and effort on my part. Once I’ve found an answer I’ll usually do a little bit of double checking – perhaps others have added a comment to say that it worked for them – and then I’m happy to accept that it is correct, knowing that if it’s not I can always head back to Google and start again. Caveats apply here, of course, depending on the severity of the issue I’m dealing with.

My point is that I freely trust the information I find based on some cursory checks, I am fully hooked into the Web 2.0 world and believe in the wisdom of the crowd (thankfully I have evidence of this as well, it’s not all hearsay).

Providing information and answers is a key part of our job as technical communicators but I am concerned that my view of the information world and how I use it may be tainting my thoughts. Do the people who use the information we produce really want to ‘just google’ for information? Am I projecting the way I think and work onto the people who use our documentation?

The obvious answer is to ask those people, and I’m in the fairly lucky position that I can do just that. A large portion of our documentation is used by our own staff, so I have direct access to my audience. So, obviously, I should just ask them: “How would you like to access the documentation?”

But I think that’s the wrong question.

Whilst it will be useful to hear the answers to that question, it is far too open ended and, to repeat an old adage, ‘the customer doesn’t always know what the customer wants’. Instead I need to figure out what the most common usage scenario is and work from that, before presenting a limited set of choices from which the audience can make an informed decision.

One thing is certain, the way I access information, the way I think about how information is structured and presented, from my professional background and my knowledge of some of the information design theories that are in use, is very different from the way I use information in my day to day life. The more I find myself leaning towards more ad-hoc, random and casual sources of information, the more I begin to wonder if the world of the professionally written and presented technical communications needs to change tack and find a comfortable middle ground, embracing all that is good about the web 2.0 internet.

Social media works because it is based on people and the availability of information (and metadata about that information). It seems all too obvious that the world of technical communications needs to make bigger strides in that direction. Many technical writers have started that journey, and whilst it means yet another set of skills that you’ll need to learn, ultimately it means that the technical information you produce will be more valuable in the longer term.

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right?

A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help.

It’s this last area that I’m currently working on.

Our product has undergone some exciting changes, and the previous set of documentation was both very document-centric and , in my opinion, badly structured. We are shifting more towards a ‘traditional’ SDK approach and as such a lot of the existing documentation needs to be adapted accordingly.

Thankfully it’s largely an exercise in restructuring the documentation rather than completely rewriting anything, but it still warrants discussion with the audience as to how best to present the information they require. In that respect I’m lucky to have direct access to a representative portion of the intended audience as the bulk of the audience will be our own staff.

The functionality available in our development kit is broken into sections, with the documentation split along similar lines, and as such whilst the information in the current documentation is fine, it no longer makes sense to have it structured that way. Breaking down all of the documentation into smaller, more manageable chunks, before deciding how best to piece them back together is the current focus.

Thankfully, in preparation for our move towards single source, we had already audited our content and so, if nothing else, I have all the discrete sections of each of the current documents already list in a ‘management friendly’ spreadsheet.

So, with a bit of manipulation I can easily mockup a sample set of information topics, and then figure out how best to present them to the audience, be it PDF, online help, or via the web.

Once we’ve got a good idea of our final deliverables, I’ll run them past a sample of the intended audience to make sure they are both what is required and to set the expectation of what we are, and aren’t, delivering. Hopefully, gaining buy-in to our plan as early as possible will mean the information we provided is better received and may even start further discusssions around future improvements.

There are some fundamentals tenets of our profession that are widely accepted. One being that you always need to know your audience before y can begin to understand their needs and so produce the information that they require.

The reason I mention this is because, whilst it’s something very basic and is deeply grained in the technical writer part of my brain, I keep forgetting it.

Let me explain.

I’m currently working on a mini-project aimed at making sure the language we use and the things we talk about through all levels of our product information (from the website and marketing brochures, down to the lowest level of reference information) tell a consistent story. From basic facts and terminology to the concepts we need to convey, it’s important that everyone throughout our company talks about things the same way.

As such we’ve modelled the information into four layers with each layer (roughly) representing a broad layer of user and information types. These types match our engagement model and will allow other areas of the company to understand not only what information is required but, most importantly, WHO the information is for.

I’m writing up a summary document (covering two of the four layers) which will cover the main areas of the product and what language and terms we want to use. The document also outlines the basic concepts of our product, and for each concept describes the level of information expected. This will allow others to build specific documents at the appropriate level, focussed on the correct user type, using the correct language and terminology.

The trouble is that I’ve really been struggling to get my head around it and I was finding it very hard to write the descriptions for each conceptual area. I was mentioning this to a colleague earlier and that’s when it struck me.

I’d forgotten who I was writing for.

The summary document is aimed at internal staff, but is covering the information likely to be required by two different types of reader/layer. As I’ve been developing this information I’d lost sight of that and was trying to write one piece of information for two very different types of user.

So, I’ve decided to split the summary document into two, one for each type of reader and I’m already finding it much easier to structure the information accordingly.

I know I’m not alone when it comes to this kind of thing, that it’s very easy to become blinkered to everything else when you zero in on a particular task. I’ve been working fairly closely with a colleague on this but hadn’t spoken to her for a few days and, without that check in place, I’d started to lose sight of the big picture.

And yes, I know this isn’t rocket science, but hope it may serve as a timely reminder to others or at least let you learn from my mistakes.

Why would you choose to make something difficult to use? Are you deliberately putting barriers in the road? Or are you just forgetting the main reason why people pick up a document or manual?

Long ago, when I had just started out as a technical writer, I attended a course on designing for Print. It covered many things, from typography to layout and I still use some of the basic design rules I learned way back then.

Whitespace, choice of font, and hierarchical indentation can help make a document more readable. Clearly delineating the structure of a document without explicitly stating it as such, leaving visual clues to help the reader navigate the page (presuming you’ve covered the multiple navigation routes they’ll take to get to that page of information).

Such considerations will continue to become more important as more and more information is moved online, and is then available in a variety of media formats and devices. Structuring your content, and using visual clues to convey that structure clearly, will become ever more important.

At this point there starts to become an obvious overlap with usability, pushing technical writers to start thinking more in terms of the user experience than simple task analysis allows. Understanding the reasoning behind a user action will become equally important, and can be passed to development to influence the UI as well as directly impacting on how we present technical information in the future.

Beyond that I’m not sure where else this may take us but I do know that part of the reason I love this job is the cross-over we have with so many other professions/industries, and I can’t wait to see what is next over the horizon.

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

The question above was prompted by a presentation I attend last week, given by Paul Sherman on behalf of the Scottish Usability Professionals’ Association, entitled: THE PERPETUAL SUPER-NOVICE.

The basic premise is:

the tendency of people to stop learning about a digital product-whether it’s an operating system, desktop application, Web site, or hardware device.

A simple example: Someone who has learned that you can cut and paste text in Word by using the Edit menu options and the application doesn’t support them learning how to do the same thing in a more efficient manner.

Many applications (and the documentation that supports them) is aimed at either getting from beginner to novice level, or getting from some kind of mid-level up to expert. There is a huge gap in application design (and, again, the documentation that supports it) around helping users get the most from their usage of an application.

That mid-level area is what Paul refers to as the Super-Novice:

in the absence of extrinsic motivation, it seems that many people stay novices or, at most, become a form of knowledgeable novice that I call the super-novice. Super-novices know a lot about the limited parts of a system they use regularly and almost nothing about the other parts

Obviously the presentation was focussed on usability and application design, but it got me thinking about how documentation, or perhaps we should be calling it supporting information, suffers in the same way.

It’s fairly easy to get into the mindset of the beginner; presume the reader knows nothing and assume a level of learning in which to frame the information. Expert level information is a little trickier but could be stated as specialist, or niche, information.

But what of the super-novice? If we want people to get the most from our applications (and we do, don’t we?) how do we enable the super-novices and help them become experts?

Paul touched on some of the aspects of web 2.0 communities, and how providing “achievement motivation” is a key method for enabling learning and helping build the “need for mastery”. At this point it is easy to see that traditional documentation, printed manuals or online help, will fail the user in this aspect. It simply can’t respond to the differing needs of the audience.

Of course there is still a requirement for those carriers of static information, but to really enable your users you need to start thinking beyond a simple push of information.

Looking at the current crop of social media networks and communities, it’s easy to pick out some common themes; there is always a core group of users who will soon become forum experts, reliable and helpful members of the group. These are the experts and the challenge is to help everyone else get to their level.

I’m still not entirely sure HOW one goes about that, but it’s clear that if this is an issue you can identify with, and that your audience acknowledges, then you need to start looking around for some new models of learning. The internet is full of them, just find a burgeoning online community and see how things work there and try and match it to your own audience.

The times they are a’changing, and those gaps in your documentation will only get bigger and soon, alongside the application, you may start to lose your audience. We need to consider those gaps, the line between A and B, and figure out how to help our users traverse it safely.

—-

Paul writes on usability issues (and more) on his blog, and for UX Matters where the origin of the presentation can be found (and from which the quotes in the post were taken).