User documentation - Does it matter?

It's very hard to tell how much user documentation matters to people. One completely un-scientific way is by looking at the messages on Twitter, on any given day, that make mention of it.

Below are some of the messages posted on Wednesday 4th March 2009 that mention documentation.

We've omitted those messages that relate to legal documents and others not relating to user documentation, and we've removed the poster's name. Some people are motivated enough to post a message because they hate the user documentation they are using; some because they like it so much; and others because they hate writing it.

Here they are:

Writing Documentation (sigh)
Documenting the documentation. I should burn these someday.
Rewriting some old VB5 apps that don't have any comments or documentation.
Mired in documentation hell. Can't take any more so off home to flop in front of telly with Pino Grigio.
Yeah, why AREN't you using Groove yet? Now I gotta put all all documentation on some old media like CD or USB
Using Fiddler to inspect S3 requests from S3Fox - now that's faster than reading documentation!!
I like the concept of Capistrano but the lack of documentation is alarming.

Trying to use 2 spot colors with pdflib in PHP. Also trying to think of an even more obscure, documentation-lacking task. Failing at both
When did the Wordpress API documentation go to sh*t?
Pulling together blog content for mvccontrib.. Anyone have a preference on what feature needs documentation in MvcContrib
It's crunch time. documentation review final stages commencing. t minus 2.5 days to finish.

Why I always understand the documentation with mistaken meaning
Another day writing documentation ... good times. (yawn)
Documentation or help sites are next to useless without a search!
Time to brush off the GMaps API documentation, right, right?
Ahh cool. i do have the notation guide, i think i'm just impatient haha. i basically only use it to update documentation!
Writing Documentation
Is working on an endless series of software installs and documentation... Yaaaay...

Wishing Cappuccino actually had some proper documentation and decent tutorials, I suppose it is early days though.
Is back to writing documentation
Listing to Explosions in the Sky and writing documentation. Not exactly Zen meditation, but close enough for this morning.
Cursing inadequate documentation. But going out later for drinks and canapes, mwah mwah

Eurgh! More documentation. I'm frakkin' siock of documentation!
Motivation issues again. Revisiting an old project and rewriting documentation isn't my idea of fun.
Dear Apple, This documentation is not good enough for a parameter called userInfo: "The user info the new timer.". Thank you, Dave.
Reading documentation.
Frantically writing documentation and updating config for a big release... no joy to deploy ;o)

Taking screenshots and writing boring documentation
First I have to finish programming it, then outcome 3 (testing it then 5 test journeys + documentation + screengrabs) then outcome 4
Ok so maybe so far documentation day isn't so hellish.
Taking some Mac documentation we did and creating the same docs for Windows XP. Surprised at what works on XP, as well as what doesn't.
Congrats on the upcoming worldwide Documentation Sprints

Congrats to @add1sun for winning one of the 6 Knight Drupal Initiative winners for documentation sprints. w00t!
In place of proper documentation (coming soon), here are some lengthy release notes for WebComic 1.8 & InkBlot 1.3
Getting intimate with Adobe Acrobat as I create boatloads of documentation for our SACS review next year. Brain turning to mush!
Do it! Joomla has a bit of a learning curve. WP is great for blogging and has its
own CMS as well as a plethora of documentation.

Writing documentation for SMARTY FUNCTION OF DOOM. Seriously, that's what it's called.
Canon Professional Services documentation almost as nice as apple packaging!
Putin mais quand est ce que ces putains de projets open-source fourniront une documentation complète d'utilisation...
Proofreading is a very valuable skill to have when writing technical documentation and specifications

Printing the Admin Guide for Respondus Lockdown Browser prior to installing it for our 8-week pilot test. 12 pages of documentation. yay...
Researching twitter for documentation use -- ideas, anyone???
Writing up documentation on maintaining the RSS Feed. I hadn't realized just how many steps there were until I started writing them down.
JCE is also a lot easier for novices to use which means less documentation.
Just baby barfed!! Doing more documentation!!!
Today is documentation day. Oh joy. How can I make this fun?

Pouring through PayPal API documentation
IT Intervention ep. 4: Sysadmin gets out of control setting up 55 virtual machines with no documentation, standards or even hostnames.
Writing another CMS documentation for a website which is due to go live next week.. 25 pages thus far.
Hello, software documentation writers: QuickStart is two words, separated by a space, that thing beneath your thumb.

Documenting processes. Not exciting, but it's better than not having documentation!
Looking into using the Amazon Seller Central SOAP API but documentation seems a bit sparse, not great for company like amazon
After many tries to undestand values of a MATRIX 3D and iam at the same point. Can't find a great documentation or sth to solve that!
Writing help documentation might be useful but it still sucks
Breaking my balls with springsecurity.. reading its documentation! o/

Why bother with user documentation in recessionary times?

Although many organisations see user assistance as a "good thing", it's not immune to the belt tightening that many organisations face in times of difficulty.

Business expert Mike Southon recommends that in recessionary times, organisations should focus on getting sales from existing customers - so customer retention becomes ever more important.

There's a virtuous circle of a customer finding user assistance helps them and becoming a loyal and happy customer. Whilst user documentation can help with the perceived quality of a product before the sale, its key value is in keeping customers: customer retention in marketing-speak. It's the philosophy of Toyota and others - the focus on quality and customer service.

Chris Bose of In Press PR Ltd, told me that recessions are the times when market share changes. This is why successful companies reduce their advertising spend, but never cancel it. They know that when the economy turns and business improves, they'll get more sales than the competition - more sales than they ever did before, most likely.

Recessions are also often the times of greatest technological change. The Great Depression saw the wide-scale introduction on electricity to houses in Britain, and, today, we're seeing significant developments in Help Authoring software. Those companies that can adopt these new developments in user assistance now will be able to differentiate themselves from their competitors - something of importance in these highly competitive times. As the economy swings upwards, this competitive edge will make a difference in sales.

However, it can very hard to measure the effectiveness of documentation. Again, this is where recent technological changes come into the place. A number of Help tools now enable you to measure how many people accessed your documentation, whether it assisted them or not, as well as many other useful measures. Indeed, Web based user documentation can be the trick to increasing your Search Engine rankings (but keep that a secret!).

It may be that you can provide better user assistance for less money. You may find you save on translation costs, lower support calls and lower printing costs.

Perhaps the question should not be "why bother?", but "how can we do it better?"

Will Twitter change the way customer service is provided?

The debate about the usefulness of Twitter in User Assistance (aka technical writing) is starting to take off:

Charlene Kingston will be speaking at the WritersUA conference in March about integrating Twitter.

The Carphone Warehouse has started to use Twitter to support its users.

See
"Mind the gap" and guy1067 on Twitter


Uploaded on authorSTREAM by ellispratt

The paradox of the guided user: assistance can be counter-effective

Christof van Nimwegen's PhD dissertation, "The paradox of the guided user: assistance can be counter-effective", concerns how software affects brain processes.

According to news reports (I've not read it yet), he claims a great deal of software turns us into passive beings, subjected to the whims of computers, randomly clicking on icons and menu options. In the long run, this hinders our creativity and memory.

Van Nimwegen said his study demonstrates people may benefit if they continue to study new information by using books and the spoken word: "Listening to someone is the best guarantee to absorb information and store it permanently in one's memory,"

User Assistance - You've come a long way baby?

The MgmtSIG digest pointed me towards the Bitsavers' Software Archive (http://www.bitsavers.org/), which stores documentation and software for minicomputers and mainframes from the 1950s -1980s. It shows how far user assistance has come, particularly in terms of graphic design.

However, there are still areas where we could learn from the past. The digest referenced MiTTS (Minimalist Tutorial and Tools for Smalltalk - http://users.edte.utwente.nl/meij/smalltalk.pdf). Apparently, this guide was a pioneer of the minimalist approach to documentation championed by John M. Carroll. It's the main approach online Help authors and Web designers use today.



The document begins:

"This tutorial is deliberately different from other programming instruction you have seen. It does not start off with a long drill on syntax and an example program that prints “Hello World.” Instead, it allows you to experience Smalltalk as an integrated software environment for object-oriented programming. In this minimalist tutorial you learn Smalltalk by analyzing and enhancing a simple but real application, a blackjack card game. You climb the Smalltalk Mountain by starting at the top!"

This leads me onto the themes of my talk at the UA Conference Europe 2008, concerning how user documentation is likely to change in the future. I suggested we're likely see these developments:

The findable manual - users can find the documentation when they search on Google.
The read/write manual - users can write content was well as read it.
The remixed manual - users can remix the manual to suit them.
The community/collaborative manual - users can comment and share ideas.
The distributed manual - the content will be republished to many different places
The manual as a portal - the manual is a launching pad to other related user assistance

The user assistance we produce today may look as antiquated as the Bitsavers' examples sooner than we realise!

How can we make online Help as natural as breathing?

One of the themes of every Help related conference is that some users are reluctant to use Help. Help, as a word, implies failure and, it is said, Microsoft spent a lot of time trying unsuccessfully to come up with a better word to use.

Recently, I was pointed towards a presentation by Professor Dan Gilbert on happiness (on Ted.com) and a book called "How Children Learn" by John Holt. Dan Gilbert stated we are reluctant to learn from the experience of others. Holt stated chilfren are natural learners, and will learn more if we let them explore their worlds.

Could we incorporate their ideas into the ways that Help (or User Assistance) is delivered and provide a better solution?
Should we could get users to access user assistance information before they get stuck, or will users always try to muddle through?
Can we make content more imaginative, and would that help?

Augmented reality gets closer

Earlier in the year we blogged on Nokia's plans for augmented reality and how it could be used for user assistance. Developments are moving apace, as can been seen by this demonstration from Japan: