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/


Louis Marascio

Ellis, That’s an interesting way to gauge frustration around documentation. I have to believe that documentation absolutely does matter, but for a reason that might be different than what most people think. Your documentation is a way to engage with your customers at a time when they need you most: when they need help or when they are open to influence. Worse yet, bad documentation has a significant negative impact on your customer’s perceptions of your company or your product and that negative sentiment lasts beyond the initial, “Man this documentation sucks” reaction. Check out these two blog posts for a bit more about what I’m talking about:

Documentation Feedback: Don’t Ask if You Don’t Care

Does Your Documentation Suck?

Take care,


Bad docu, like the poor, will always be with us. It happens for many reasons, all of which reinforce each other:

a) it’s a global village, with a whole lot of folks speaking some variety of English (Germlish, Japlish, Babu, Pidgeon…) whose syntax does not quite add up, either to native speakers or to speakers of any other variety.

b) developers are writing about stuff that, AFATC, ought to be IOTTMCO. They’re going to leave stuff out. Lots of stuff. Important stuff. (BTW, If you don’t understand the acronyms, GTFO.)

c) The more troubleshooting you write in, the lousier your software will appear to be. Never mind that your docu (and you) will be more helpful. It’s all about first impressions.

I personally wouldn’t mind bad docu quite so much if the various help forums weren’t populated with individuals whose grasp of communication is even weaker than developers’. I think it has to do with the flow of info demanded of us all in this intertubes age. It overloads your processing centers to the point where, if you can clear your head out and be concise and complete about anything, you’re probably not doing your job.

It would be great if the 3rd world weren’t leading the market in software development. They can’t write good docu, nor will they be in any position to for a few generations yet.

Rainer Ottmueller

Howdy Frank,

Please, let me try to clarify the viewpoint of the rest of the world. Here I’ll also try to meet your level (aint easy).

> a whole lot of folks speaking some variety of English

Most of the native speakers, the users of “phrasal verbs”, disturb by their “strange” usage. As an explanation: to use English is good for sales.

> if you can clear your head out

In case of neccessity, I’ll ask someome who knows what he is talking about.

> be concise

Would not this reduce the size of your post, significantly?

> It would be great if the 3rd world weren’t leading the market in software development

Also, “world peace” would be great. Don’t you agree?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.