How clear is your product documentation? Not as clear as it could be.
I went to “Family Morning” at my 5 year old daughter’s school yesterday. I walked around the room, looking at the work she has done, reading the story she is working on and getting to know her new friends. Then I saw the chart that showed her how to pack up and it stopped me dead in my tracks.
This is the ULTIMATE user’s guide poster. It is 2 feet by 3 feet. There is nothing challenging about it. Each step is self explanatory, down to having a little picture to clarify the step. I almost started screaming out loud! This is AWESOME!
Please tell me that you’ve got a pre-schooler on your staff that oversees your documentation creation. I would pay big time to have documentation for software this simple and creative.
Granted, software is a little more complex, but for the End User, does it really have to be?
I like this… a lot!
Great example Mark! It just goes to show that clear use cases drive simple documentation!
I would agree with @erica. I have found that many IT people do not look at the idea of documentation from an end user perspective so the information is either way to complicated or does have enough detail. The use of pictures is a nice touch as well :-)
Man…now I wish I had bothered to write up something like that for some of the sessions I hold with my users – more than once, I’ve felt like I was talking to pre-schoolers :)
An alternative to toddler labor, and to avoid child labor laws, you might consider hiring a Mother of toddlers. They have learned to give instructions in much the same manner.
When my twins were two my husband asked me where something was. Instead of simply saying under the bathroom sink I launched into something like “Go up the stairs, down the hall, and into the bathroom. Once you are in the bathroom, stand in front of the sink, open the cabnet door under the sink. . .”
My husband looked at me like I had finally gone off the deep end before carefully replying. “Uh. . .I know how to look under the sink”
The ironic part is that after giving these steps inevitably they would get up the stairs then yell down “What was I looking for?” Much like a user does.
Trudy
ROTFL!! Love it.
I absolutely agree with every said. Especially in IT projects the documentation is very often as poor, as if you have no documentation. I see two reasons:
1. Creating a good documentation is a very time consuming process. If the enduser should get a picture book, the author has to do each single step. If it is a straight forward process, it could work, but if you have decisions in the process to describe, it could be very unhandy.
2. Very often IT guys and endusers speak in different languages. The IT members cannot describe the solution in the words, an enduser can understand.
I don’t know, if there is a simple solution for this, but I think we have to work on it, to make the enduser’s life easier.
Olaf
I have to say I am a more vs less person in terms of documentation, as it helps me identify weaknesses in processes that may be overlooked in the big push to get things rolling. I have tried to force myself to do more along the way, which can help.
Our user base runs the gamut from very tech-savvy to near-Luddite so it gets difficult to know how far I have to go in terms of spoon-feeding; we also have most users running Office 2003 while a portion runs Office 2007 and some on Office 10. A uniform level of skill plus a uniform platform would help immensely. I often must write 3 versions of the same thing.
The challenge typically is that the more the documentee knows the more things they consider in their process flow.
1. Get Your Backpack and Jacket.
Seems simple but a technical or knowledgeable person might be tempted to change it or potentially over think it:
1. Get Your Backpack and Jacket.
Exception: If You did not bring a backpack or jacket move on to step 2.
Mock Questions: What if they brought an umbrella? What if they brought a coat? Is that the same as a Jacket? What if they brought multiple backpacks or share a backpack with another classmate such as a sibling? For Step 2 – What if your lunchbox is already in your backpack? etc
The problem people, organizations, and technology faces is that we try and be complete in documentation. The reality for most user driven documentation is that you must accept it WILL NOT BE complete. Instead it will focus and outline the most important steps only etc.
Thoughts?
I am going to stick with my “hire a mother of toddlers” theory but may want to ammend it to “hire a mother of very smart toddlers”.
Since smart toddlers are very good at firing off multiple questions in quick succession all while finding ANY and EVERY loop hole in the instructions given, these mothers have learned to give instructions that anticipate all those questions and stall tactics.
So they end up sounding something like this. . .”Go up the staris, and down the hall. Do not stop in your brothers room, pet the dog, or poke your sister. Go into the bathroom and stand in front of the sink. Do not turn the water on, play with the tooth brushes, or drop your hot wheels car in the toilet. . .”
I have so totally been there, and said that!
But seriously, It is sometimes easier to write instructions for someone who doesn’t have as much experience or knowledge because they just follow the instructions given to them. The more knowledgable users are like those very smart toddlers finding the hole in every instruction given. In some ways you have to accept that there will always be that user who will find the one thing you didn’t anticipate. In those cases I update the manual as best I can, and move on. Instruction manuals are always a work in progress.
Trudy
Richard makes an excellent point but let me take it a step further and say that not only will any type of documentation never be complete but you shouldn’t base your product documentation “model” soley on step-by-step documentation (or simply any documentation for that matter).
In order for your product documentation to be effective as a training or instructional tool (as I assume we are discussing here as that seems to be where the responses are gravitating to) you have to include other mediums to get your message out to the people that need it (your end users).
It’s key to remember that everybody learns differently and while some might be able to get by just fine by reading a document that lays out a process or procedure in a step-by-step format (read-write learners) there are going to be just as many (and likely more) folks that have to “see” the process completed visually (visual learners) in order to grasp the concept. It’s very likely that even more have to actually walk through the process or procedure themselves to grasp the concept (kinesthetic learners) .
That being said I am a firm believer that any kind of product documentation that is intended to be used as a training/instructional/informative tool should not only leverage documents but should also include videos (Camtasia does a great job and is my tool of choice), one-on-one or classroom training and remote (webex, go to meeting, Live Meeting etc….) training of some kind.
The key is to make sure that you reach all the levels of skill and expertise in the organization you support without talking down to them or talking over their heads. It’s a VERY narrow target and can be incredibly difficult to hit accurately without a lot of trial and error.
Oh yeah…..don’t forget that you have to reel in those folks that are resistant to change, they change your dynamic quite a bit and you really have to adjust your documentation to show them the benefit of performing a task or procedure in the manner you are describing as well as showing them how to actually do it. This group will be the one group that you definitely need to plan on using face time and actually letting them walk through the process or procedure so they can see the benefits of what you’re trying to get them to do.
I would think you could use a sharepoint site to create a multi-media training site. Maybe with a wiki for the read-write learners.
The wikis could then also contain links to training videos stored in a video library for visual learners.
If you could find a program that would allow you to create some sort of try it yourself where the users could see if they truely understood how to do by try it in virtual enviroment you could create for the kinesthetic learners. You could add links to that to the wiki as well.
Maybe a discussion board for the community of users, where users could post questions about some of those out of the norm situations and other users could share their solutions. After the solution was found you could maybe have certain power users that could have permissions to create a new wiki document and keep elvolving your documentation.
Just sort of thinking out loud here.
Trudy
and thinking out loud quite well.
I typically create a Training & Support site collection and have a document library with 1-2 page “How-Tos”, an FAQ along with a link to submit a suggestion for a FAQ or to ask a question, another document library that uses HTML pages that call embeddedmedia player to play the videos.
I use subsites of the Training & Support site for one-on-one and classroom training and exercises.
I do use the Microsoft SharePoint Server 2007 training that you can install on the server or on your desktop.It’s more than most folks need but with a little tweaking can be a great benefit to have and it can save you some time developing your own videos if you decide the MS stuff is worth using.
I also have a “playground” or sandbox for my really interested users to play in. I’ll give them their own site on the server and make them a site admin and turn them loose. They do have some guidelines they have to follow but I give them pretty much free reign.
Thought about wikis and didn’t want to use them in our environment (C-level exec decision)
Everyone brings up a very good point. My wife and I raised 5 kids and both were active duty Army and used some or all the techniques mentioned. I my current position as the hospital SharePoint/Web Administrator for a military hospital I find my using PowerPoint slides with ‘pictures’ helps a lot! Doctors and Nurses I discovered are more ‘visual’ learners and I place myself in that category. My wife is a nurse working for the Army at the same hospital. When she talks to other ‘providers’ they say, “It was easy to understand how to use SharePoint with the slides and using the computer. I set up a FAQ on our IT department SharePoint site with all the classes. Whenever I get a “How do I do… question or work order,” I put together slides and post them to the site. The slides are used every day (Set up an ‘alert’) to track the usage. My point is, “You are never too young or old to use visual aids to give instructions.”
Frank, sounds like you got the good side of the Army. I break out a slide deck and people run away……….too many meetings that are PowerPoint driven with 100+ slides to cover in the alloted time.
Interesting NY Times article on “Death by PowerPoint
http://www.nytimes.com/2010/04/27/world/27powerpoint.html
I two sets of slides, one for the class I use the outline format alone with hands-on with computers. The other set I post is the ‘Death by PowerPoint’ step-by-step slides.