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

The tool is not important. The tool is not important. The tool is not important.

I have been repeating this mantra in my head for the past week or so, over and over, like a broken record. I’m in the middle of pulling together the requirements and scope for a new technical community website for our users, which will become the key focus of our technical information. The more traditional product documentation set will be maintained as we move forward, so there is some thought to be given towards how we manage the information as well as how it is published, or rather where.

I must stop considering the how. The tool is not important.

At present I have a list of requirements, all of which I’m thinking through from the point of view of how the process will work as far as creating and maintaining the information. Who will be access the source, who will be viewing the published information, who can edit what, how will the information be used by the audience? All the while there is a part of my brain dragging me towards HOW this will work. What tool will be able to handle our requirements?

The tool is not important.

I enjoy a challenge, and this is most certainly a new venture for me, but the basic foundations of this idea are rooted in things I know well, single sourcing content, developing online communities (I run a website for Scottish Bloggers (currently dead after our hosting service disappeared)). As such I’m confident I can get this off the ground, but even so I’m being careful to properly gather requirements, and fully understand the impact of changing our publishing model. Note I said “model”.

The tool is not important.

So with a list of requirements, and a full understanding of the processes that will be involved both to maintain the main documentation set and the development of other supporting information (culled from internal Wikis, mailing lists and anywhere else we stumble across something useful) one change is the way in which we plan, design and write product documentation.

As I’ve said, this is all about the processes that support the way we work. I’m being quite deliberate in how I pull together the requirements, focussing discussions on the audience, the expectations, the information and processes, with no mention of the technology which will need to support the new website.

The tool is not important.

Last year’s X-Pubs conference drilled this message home, and it’s good to be able to draw on the information and knowledge gained there. Get your requirements sorted out and agreed, understand the impact of changing the way people access information, and the impact of changing how people work, figure out how best to handle the reaction to change and agree the expectations and limitations of your system. Decide which models you will follow, how the processes will hang together and outline the various roles that will be required, and make sure they understand what is required of them.

Then and only then should you consider what tools you require and make sure they are serving you.

Deliverables are dead. Long live multi-format, anytime, anywhere delivery of information!

The more I think about it, the more I am beginning to see that creating content, writing and styling and planning, for “print” is no longer valid.

Quick caveat: Know your audience and the requirements. Many places mandate printed documentation in one format or another. I am purely talking about my own experience in a software environment.

I’m the first to admit that whenever I start thinking about updating a manual I think in print terms. I think of entire chapters of information, I think of how the user will be able to navigate and understand the layout and construction of the document. Changing those habits is proving hard but I’m slowly getting there.

Part of that change has come about by focussing on the information types we are going to be using as the building blocks of our single source system. Making each topic unique and complete within itself requires some thought and planning, and with that planning being focused on tasks, you soon get a simple outline of the required documentation including the type of information that you’ll be writing for each chunk.

As that realisation begins to sink in, the possibilities of re-use suddenly make themselves clear. It becomes a simple matter of drag and drop to create an entirely new manual, and a new delivery method becomes a simple matter of publishing to a new format.

The latter fits nicely with some current thoughts around how we get our technical information to our customers. Whilst I don’t think Author-IT would be the best solution, or at least the complete solution, I can see us focussing more on a web-based delivery of information, pulling other available content (from mailing lists and wiki pages) into an MSDN-like community website. Add in a blog and some interaction and it could very well be the shape of things to come.

As I’ve mentioned before, for a lot of people in the software industry, the internet is THE source of information. So rather than try and force how we want the information to be delivered (maintaining legacy documentation) I’m looking at how we can deliver something our customers will use, without succumbing to the Web 2.0 crazies. Yes it could have a blog, but does it need one? Yes we could use Twitter to provide ‘from the floor’ thoughts from the development group but who would sanitise them first!

Wikifying the doc set (to borrow a phrase) is a possibility of course, but that would only be part of this solution, and would have to include the ability to package it up as a different deliverable (PDF for example) so the information can be accessed when the internet isn’t available, a requirement of our documentation.

There are other considerations of course, all of which are still being thought through and will need discussion and buy-in.

Exciting times ahead I think. More on this as it develops.

As a technical writer, I often find myself bemused by the design decisions made by developers and product designers. Any time I find myself bemused by a product I tend to look towards the supporting information.

However, the technical writer also has guard against such things, as evidenced by the instruction manual I received with my new watch. The watch itself has four buttons, and like most digital watches each button will do different things in different modes.

The buttons are not labelled on the watch itself and so the instruction manual is the only place to figure out what button does what. OK, I’ll admit it, I did play with it for a while before turning to the manual at which point I became a little confused.

There are four buttons, and in the instruction manual there is a simple diagram showing that they are labelled A, B, C and D. So far so good.

However, and bear in mind this is a watch so when you look at it the cognitive suggestion is “clockwise”, the buttons are labelled in an anti-clockwise order. Now if each button only did one thing, this wouldn’t be that big a deal. Yet because of the non-intuitive way they had labelled the buttons, I continued to find myself confused as to which button to push, returning to the manual at every point to check which button was next.

This is not a flaw in the hardware (the watch) but in the instruction manual.

Why do I mention this? Two reasons:

1. We are the interface to the interface. We can break the “product” as easily as we can enhance it.
2. Making sure co-workers realise that the documentation is part of the product can be tricky, and this leaped out at me as a good example. The product suffers because the documentation is poor.

I’m pretty sure this could have been avoided if the writer had spent more time with the product as there is little better way to fully understand how a product works, than sitting down and using it yourself.

That said, it is a very nice watch…

Recently, Tom suggested that:
if someone can figure out how to make help whallop the user with wonder and awe, it will be the creative innovation of the century. Once we begin to establish a standard and a precedence, people’s beliefs will change from feeling that “all help is useless and unimportant” to “the help at my company is exceptionally good and useful; I will explore it more often.”

And I completely agree.

But.

Whilst he goes on to list ways in which the future of online help may expand - personalized help, feedback options, audiovisual options and such like - I think that is only one side of the coin.

While, without a doubt I could work harder to improve the content offered as online help, I think technical communicators need to expand their view a little, step back and see a bigger picture. I’ve touched on this before, and it is by no means original, but ultimately we are at a point where it is beginning to be realised that the information provided with a product is a most valuable commodity. With that in mind, the time is ripe for what Tom suggests, a new way of presenting information is surely on the cards. However I think it’s wrong to limit it to online help or documentation alone.

I’m lucky that, presently, I’m part of a company that allows the Publications Team (MUST change that name!) to be part of the softare design process. As such I can see, from inception to release, the decisions and design thoughts that go into producing our software, and I influence them as much as I can. Making the on-screen text useful is one thing, the next step is to think “task task task” during any discussions on design. Developers, rightly, take a requirement and start thinking about how THEY can implement it, yet just by repeating the “task task task” mantra I was able to get them to start thinking about how it should end up, rather than the finite possibilities of how it could be implemented.

Just to clarify, I don’t sit at my desk and chant. Instead I tend to start discussions about our software with “OK, I’m [insert user type], what am I trying to do here?”.

I’m not ramming this down anyone’s throat, but my choice of language during discussions has started to rub off, resulting in some design decisions made because they were thinking about the task the user is trying to complete, not the fact that it would need to get info from database A and publish it to form B.

In response to Tom’s post, I said:

Perhaps the radical shift is helping to address issues without presuming that people will “end up in the help”. Instead of being the last resort we should be striving to stop people having to get to that point.

That said, if they do end up in the help then yes, it should have a sufficient “wow” factor without being useless. Ultimately, make sure the information they want is findable by whatever means they choose.

Being the customer respresentative, the interface to the interface, is part of that.

I once told a Technical Support Manager that, ultimately, the aim for my team was to put his out of a job. Obviously that will never happen as the myriad of platforms, hardware, and user issues that surround every software product couldn’t ever be documented (unless development of the software had ceased, in which case I wouldn’t be working for the company).

I guess the aim for a usability team, or anyone interested in improving the user experience, is to put the documentation team out of a job. If the interface is well enough designed that the user doesn’t get stuck, and if it includes enough information in the UI to help the user make decisions, then why would they ever need documentation? Of course, similarly to the Support team scenario, documentation will be required to support the less travelled paths through the UI, to help the user who wants to do things her own way.

And that is where Tom’s suggestions come in. If we can improve the information we provide, making sure the customer experience is maintained (bettered?), then they are more likely to come back.

As I mentioned previously, the opening presentation at TICAD was by Adobe and featured their vision of the future of Technical Communications and information development. Apparently that future includes video.

Video has been available to many for a few years now, yet it is never really the main focus of a documentation team. Tom has questioned this as well:

“For too long I’ve minimized the importance of the audiovisual. Captivate — the industry standard tool for creating screen demos — is actually a relatively simple application. Mastering it and integrating audiovisual into user help will take it to the next level.”

This echoes what Adobe suggest, no big surprise there, but I have to admit that I don’t fully agree.

As a quick learning tool, I’m sure videos (screen demos) are useful, but I wouldn’t really know as I’ve never used one as a primary source for learning about a product and I’m not sure I know anyone who has. Of course that’s not to say they don’t have value and with some research into the intended audience I’m sure it can be proven that they have a valid place in the product documentation set.

However my initial thoughts on the matter are hard to shake.

It may be one of the unwritten rules of documentation, the rules that few people question and may well be inaccurately applied, but I’ve always operated under the assumption that people only use the documentation when they are stuck.

Of course this is a broad sweeping statement but I believe that it is true for the majority of software users. So, if that is the case, what is their mindset when they finally give in (having asked a co-worker and searched Google to no avail) and fire up the online help or open the user guide? Typically they will be annoyed and want an answer or fix pretty damn sharpish.

Why, in that case, would they even consider sitting through a 2 minute video that explains how to use the functionality with which they are currently battling?

To be fair, Tom isn’t suggesting this approach but I think it’s wise to counsel against this trend lest it be used too heavily. A few short demos of how to complete core tasks, accompanied by a comprehensive help system or user guide is the best balance.

My fear is that the “cool” effect will override sensibilities and we’ll be plagued by popup videos and worse in the future.

The written word certainly isn’t the only way to effectively communicate information, and as technology progresses we will all need to carefully match the available delivery mechanisms with the information we need to deliver. The key word here is “carefully”.

I’d love to hear from anyone who is already doing something like this, I’ve not used Captivate, nor offered any form of video as part of a documentation set before as they didn’t match the audience profile but I’d be interested in hearing how successful they were.