Writing User Guides and Training Scripts

[Lunatic]

Here's the skinny of it: I'm hoping to draw out advice from the members of this forum on how to create user guides and training scripts that are successful in relaying the necessary information to the selected audience.

Any advice you can offer on things like:

* How to write a training script to introduce an audience to an online database driven system

* Things you have found that maximize the usefulness of screenshots in user guides

* Any suggestions on how to avoid confusing retirees when introducing an online, database driven, system (a very large chunk of our field staff are retired educators)

* Pits or traps you've learned to avoid when talking about systems

* Is it ever better to give a slide-show presentation of a system than actually conducting a live demo?

I'm having the most difficulty designing the training scripts so if anyone has any suggestions or experience on how to write a training script that is going to be used by 8 different trainers at the same time I would really, really appriciate it.

 

[SantaMufasa]

Luna,

My credentials on this topic include my having been the International Director of Product Development for Oracle Education. We developed, maintained, and delivered courses worldwide, covering 500+ titles.

For your audience and your topic, I suggest the following:

* Always acknowledge that students can, and will, be successful, even if they do not have prior experience with, or like for, technology or computer software.

* Acknowledge that computers are like "idiot/savants" in that they have very little or no innate problem-solving ability, but that computers follow lists of instructions (programs) very quickly and very precisely. Computers are very "literal" and have no intuition unless programmers have "gifted" the software with some form of intuition.

* If people have problems with computers, don't blame the machinery...blame the programmer(s).

* Always acknowledge the worth of every student question. Never belittle what may appear to be "stupid questions", else you will lose the "inquiring mind" (and possibly many others) by such insensitivity. (Remember, you can "park" any inappropriate/untimely questions in a whiteboard "Parking Lot" for answering later or off-line.)

* Never use "techno-geek techno-speak jargon". Always use terminology that your audience natively understands, else define new terms.

* The best tutorials are ones where the instructions match the on-screen results. (You may laugh, but I've done tutorials that didn't match software behaviour.)

* It is better to have a dozen lessons that illustrate different points than one gigantic lesson that covers all the points.

* "A picture is worth 1000 words." Yes, use screen shots profusely.

* A good tutorial index is worth the price of admission. A tutorial without an index is only half the story.

I'm certain that I will think of more suggestions later.

Mufasa
(aka Dave of Sandy, Utah, USA)
[I can provide you with low-cost, remote Database Administration services: see our website and contact me via www.dasages.com]

 

[Lunatic]

Santa, you don't have to prove your creds, I've seen enough from the regulars around here that I'm going on the assumption that most people are at least as capable as I am for writing manuals and training scripts. I know when I'm surrounded by those with more skill

One thing that the grizzled vets around here are good at is reducing things to the simplest possible English and making sure screenshots are the actual system at the actual point.

When you say tutorial are you refering to the user guide or the training session?

***
Could you go into more depth on the Index as opposed to a TOC? Thats one part in the user guides I'm struggling with, is trying to figure out how to:
A) Design the index (alpha by word or alpha by catagorey); and
B) How to decide which occurances of the word to reference in the index and which shouldn't be. Any general rules of thumb would be very much appriciated.


Thank you for your comments!

 

[2ffat]

A few things that come mind in looking over the training that I enjoyed (and thus remembered best) are the use of humor and concrete metaphors or similies.

When using humor, make certain the audience knows that you are intending to be funny. Don't over-do it. A little humor/anecdote goes a lot way if applied correctly.

When introducing new concepts use metaphores or similies that people can relate to. For example, I remember being taught that a last-in-first-out (LIFO) que is like a cafeteria plate holder. When plates are stacked in the holder, the first plate in is on the bottom, thus it will be the last one taken from the stack. Conversely, the last plate put on the stack will be the first one taken because it is on top.




James P. Cottingham
-----------------------------------------
[sup]I'm number 1,229!
I'm number 1,229![/sup]

 

[SantaMufasa]

I hope that I didn't come across as trying to impress with credentials...I just wanted to convey the idea that my suggestions were not just idle thoughts that I came up with instantly, but they germinated over about 36 years of teaching and producing courseware.

When I read your posting, despite your specific references to "user guide" and "training session", my brain somehow slipped right into "tutorial" mode. Nonetheless, most of the principles that I mention are universally applicable to any medium/venue where learning should occur.

In the case of a User Guide, the notion of an index becomes even more critical. I've seen indexes that are really a concordance to every occurrence of every word in the volume -- such is a virtually useless index.

Most document processing software nowdays offer the capability to embed index references right in the reference text itself, either at the "main topic" or "sub-topic" level. (Such a feature is worth ten times its weight in platinum.) Using such a feature, create embedded index entries that you believe are stellar examples of how to deal with the indexed item. Don't just make the index a dumping ground for every reference to a particular topic.

A ToC is vastly different from an Index. The ToC is a roadmap to the chronology and physical layout of the material; typically ToCs are poor replacements for quickly looking up the location for a specific topic.

IMHO, as I mentioned earlier, an index can become the most valuable part of a text. Can you imagine trying to locate quickly, in a SQL Users Guide (without an index), the SQL syntax for a CREATE TABLE statement (especially if the text is not organised alphabetically by SQL statement)?

Mufasa
(aka Dave of Sandy, Utah, USA)
[I can provide you with low-cost, remote Database Administration services: see our website and contact me via www.dasages.com]

 

[Lunatic]

Thanks Dave!

I wasn't trying to make it sound like I thought you were acting like a peacock. I read it as you were trying to justify why your comments should be taken seriously, and at this point there are a number of people on this board who, in my opinion, do not need to display credentials and you are one of those.

James, any suggestion on how to include humor into a training script that I will not actually be reading? Instead 8 individuals will be reading what I have written? Thats a lot of my problem. I'm not writing a script for me, I'm writing it for our 8 trainers.

Thanks!

 

[kmcginn]

Speaking as a former teacher and documentation specialist, and as someone with a mom of senior age who is just getting into computers, the best advice I have is never assume they know anything you haven't told them. You can never get too basic. For example, don't say "Turn on the computer." You need to say, "The CPU (Central Processing Unit) is the tower that came with your system. Find it now (show a picture.) In the center of the CPU is the power button. Press it until you see the green light on the unit" or something similar - you get the idea. It sounds funny to get this basic, but the biggest obstacles to seniors learning the computer is their intimidation by the whole thing. If you can take away that intimidation, you'll win the audience over.

Of course, you must know your audience. If thes students have used computers before, you can be a little more advanced, but use caution not to overwhelm.

Even teaching high school Math, I found the hardest thing to learn was getting down to the level of my students - forgetting how little they really knoew. Things that were second nature to me, were completely new and foriegn to them.

In this case, pictures really are worth a thousand words. You can show someone much easier than you can tell them. However, as was mentioned before, be sure that the picture really matches what they will see.

Also, as you give examples of steps they will take and what they will see, take into account the different operating systems your students will have and try to give examples of each. Nothing is more frustrating than to try to complete an assignment and go through a process when you have something completely different because you are using a different operating system. It's not a big deal to us, but it makes a difference to them.

One story, then I'll quit rambling. My parents were keeping my daughter years ago when she was little - about 7 (she's 20 now), and they took her to their computer class. The instructor set her up on a computer and proceeded to teach the class. He was going over a topic, and the lady next to her let out a shout - "Wait," she said. "I have little things flying all over my screen!" My daughter leaned over to her and told her to touch the mouse. She did and then told the instructor it was OK to proceed. In relaying the story to me later, my daughter (all 7 years of her wisdom), was amazed that she didn't even know what a screen saver was! Out of the mouths of babes - you gotta love it!

Anyway, you get the idea. Keep it basic!

 

[2ffat]

I agree with kmcginn. Keep it basic, and know your audience. Also since you are dealing with people who will be reading yor script to others, it might help to know their personalities, too. A joke/anecdote is more likely to get a laugh if it comes from someone who has an outgoing personality than one who acts like a dead fish. I would recommend using anecdotes or puns rather that jokes, too. Don't try too hard. You just want something to lighten it up (and keep people awake ;-) ).

James P. Cottingham
-----------------------------------------
[sup]I'm number 1,229!
I'm number 1,229![/sup]

 

[columb]

Can I reinforce Mufasa's remarks about indexes. The biggest problem I've found with training notes is the difficulty in retrieving information from them in six months time.

One of the best ideas I ever saw on this matter was on a training course on IBM Tivoli backup software. The trainer had produced ten A4 pages of the common commands, grouped by type, with examples. I hardly ever refer to the formal course notes, I can nearly always find what I want in there.

See also the IBM 'man' pages, which also have examples. Once again I nearly always skim down to the bottom to look for an example which matches what I want to do, only refering back to the detailed description for difficult cases.

Ceci n'est pas une signature
Columb Healy

 

[fumei]

Depending on the situation and time constraints, one other helpful thing is to have real users USE whatever it is, and find out the 10 - 12 things they use the most. Then make a SINGLE page (but you can use both sides) Quick Reference.

When our organization switched to Microsoft (sigh.....another story), our 30,000 users were suddenly faced with using Outlook. We had training galore, with a custom done 140 page book handed out to every user ( - can you believe that crap...stupid, stupid, stupid...NO basic user is going to go through a 140 page book).

The sub-contractor was going to charge us $160,000 to make a Quick Reference. I was asked my opinion on that. I said, no freakin' way. I put together a double sided sheet on the basics...how to open a message, how to attach a file, how to get/save an attachment, etc etc etc. The basics. Everyone uses the QR...no one opens the book.

The QR was a two column table, with headings:

TO: DO THIS:


Another thing. Use Active Voice where ever possible. Keep the sentences short. Do NOT go into in-depth technical detail. User do not give a crap about how something works, The majority just want to know whatever it is they need to do their job. Give them that - what they need.

Above all - know who the audience is. Documentation for a user audience is very different than documentation for technical support people. Trying to make documentation to cover multiple audiences is not a good thing. It is much better to be able to aim for specific audiences. If that takes multiple documents, so be it.

Oh, and I don't know about your organization, but in ours we have a number of visually impaired staff. "Click" is now verboten in our documentation. These people use the keyboard and screen readers, so anything that refers to using the mouse is meaningless. The official word is "select".

If your software does in fact have useful keyboard shortcuts, it is handy to put these both in the body of the text (where appropriate and in context), but also collected in a separate Appendix. There are a lot of people who use the keyboard a lot.

Minor story: I was doing some training and typed something into a dialog and then pressed Enter. The people were astonished. They ALL thought you had to finish the typing, lift your hand off the keyboard, reach over to the mouse, move the mouse pointer to OK, and then - ahem - select OK. They had no idea they could type...and do the OK with Enter. I am still constantly surprised by people doing this, especially those staff whose job is mostly data entry - ie. typing.

Gerry
My paintings and sculpture

 

[Lunatic]

Outlook... yes, that is one of our custom training manuals. It actually is the one of most frustration for me. It was 21 pages to start with, no index, heck it didn't even have sections/chapters, just bold words every now and then. Its now 30 pages But some of that is the section headings and it has something of an index now.

Thankfully we don't have to worry about adapting wording for visual impairment. One of the requirements is that staff read a training script word-for-word, so there isn't any wiggle room, its part of our contract.

***

I like the headings you used for the QRs. We have a few of these too and that might help a few of them become easier to use.

***

This is great, with every post the picture becomes a little more focused and easier to figure out. Thank you all!

 

[SQLSister]

Screenshots are great and necessary, but they are more helpful to students if you use arrows on top of them to point to exactly waht you are talking about. Heck i get screen shots in my job all the time and can spend 10 minutes trying to figure out the problem and I know the system.

When I taught, I always had one exercise at the end where the students have to create something using the program(s) under consideration without step-by step instructions. Students need to know they can successfully do the task from what they have learned without being told every step of the way.

The quick reference guide is a great idea, also I have put together a quick troubleshooting guide for common problems. What to do when the printer won't print for example.

Another common problem with computer training is usually the examples are so unrealistic that the trainees can't directly relate them to the actual tasks they need to do. Many people have trouble making connections. S if you are teaching an Excel class to a bunch of accounttants you would have different examples than if you were teaching to a group of meeting planners.

Another thing that happens is they tell you how to do some task without ever getting into why anybody might need to do that task (take mail merge in a word processor as an example, if you don't have a real ife example of how this will make your life easier, you probably will not remember or use this feature again after the course). Ten they use an example that is so trivial to do without that feature and is so meaningless that no one in the class has a clue why this was in the curriculum to begin with. So instead of doing mail merge with six records, so it with 600. Then they can see the benefit.

Questions about posting. See faq183-874
Click here to help with Hurricane Relief

 

[SantaMufasa]

SQLSister is right on ! Always use real-world examples from the business experiences of your audience. Getting the audience's heads moving up and down, agreeing that the example is something that they have needed to do, is every bit as important as teaching them how to perform the behaviour. If your audience see no point in performing a behaviour, then typically they immediately turn off their brains/glaze over. If anyone ever says, "Why would you ever do that?" then you know you must redo your example.

Mufasa
(aka Dave of Sandy, Utah, USA)
[I can provide you with low-cost, remote Database Administration services: see our website and contact me via www.dasages.com]

 

[gbaughma]

I've done training for years. In fact, I think that if I could, I'd be one of those "motivational trainers"... the ones that really get the energy pumping.

One of my duties at work now is to "Train the newbies" (it's called NEO - New Employee Orientation). They used to have me do the IT Trainin at the beginning of the 2 week orientation period. I found myself being deluged with questions that I knew would be answered in later trainings (for example, what's HIPAA, or PCM [Professional Crisis Management]). Now, I'm at the "tail end" of the two weeks, and part of my introduction is "Now we're going to see how everything you've learned over the past two weeks applies."

Training adults is different than training students (at any level, including college). College students are in the "learn" mode... adults often come in carrying baggage such as "I did poorly in school, so I'm not going to be able to do this..." or "You can't teach an old dog new tricks"... a lot of self-fulfilling prophesy and self-sabotage going on already.

In fact, I once did some trainings at a building that *was* an old school, and watched adults actually *shaking* from anxiety just being in a school again, because their schooling was so traumatic.

Training anything I.T. always has its own issues as well. One of the first things that I say in my training is "Look. I'm a geek... I sit around all day chatting about TCP/IP traffic over a T1 and data bottlenecks. If I start using terms that you're not used to, say 'Yo. Geek. Talk english'", which always gets a chuckle.

I've had many people come up to me and state "I feel so stupid [regarding computers/software]" I point out to them that everyone has their own niche... mine is computers, but I'm lucky to know where to put gas in my car. That keeps the student's self-esteem up, and reinforces that they have their own skillset to draw upon.

Dave's initial response to the post was spot-on, and he brings up several excellent points. The only thing that I could really add to that (OMG, *finally* Greg is getting to the point!!!!) is that adults train differently than students; they often come in with their own self-sabotage, so the thing to do is:

Tell them what you're going to teach them.
Then teach them.
Then review what you taught them.
Make sure they have a copy of what they learned that they can refer back to.



Just my 2¢

"In order to start solving a problem, one must first identify its owner." --Me
--Greg

http://parallel.tzo.com

 

[Lunatic]

Greg -
Our group is a likely to be a very interesting paradox, there will probably be a signficant number of them that have the very anxiety you are talking about, however it is very likely that most of them will also have been teachers for 20 years or more before retiring ;p

Referencing your last part - I will need to go back through and provide a better overview. And we do provide a user guide for every system we train on.

My question is how extensive in the review? Unfortunately we have a severe time crunch as the training length is fixed but the number of systems or processes grows. I don't know if adding an indepth review would be possible. Do you have any suggestions on how to provide a review when there isn't time for one?

SQLSister
Its always good to hear someone reinforce what you've been doing.

Dave
You mean 'Because I said to' doesn't give enough justification? ;p

Thanks!

 

[gbaughma]

The review can just be a "recap"... that's what I usually do.

I use PowerPoint, and I usually go through "Here's what we're going to be covering", then the training, then a review with bullet points.

I give them a copy of the powerpoint notes pages before I start, but I ask them not to read ahead, I encourage them to take notes, and point out that I *want* them to interrupt if they have questions. Keeping in mind, my groups are usually about 6 people. In a larger setting, I would ask that questions be held for the end (just because someone is usually "thinking ahead" of you)...



Just my 2¢

"In order to start solving a problem, one must first identify its owner." --Me
--Greg

http://parallel.tzo.com

 

[SantaMufasa]

Dave -- You mean 'Because I said to' doesn't give enough justification? ;p

Not only that, but I point out to my students that besides being a Techno-Geek, I am a business person first. Business lives or dies by The Bottom Line...meaning: (From the business perspective only,) "If we do not create 'profit', then we are not a healthy business."


Everything we do in Business (including the classroom) should have a direct linkage to enhancing profit for the organisation. This means that whatever we do, it should either:

1) Increase Revenue, or
2) Decrease Expenses.

What we do in class should either Increase Revenue (i.e., generate more income via increased sales, customer satisfaction/loyalty, et cetera) or Decrease Expenses (i.e., cut costs via our being able to accomplish our work faster/better/less expensively, retain employees via improved satisfaction/productivity, et cetera).

So, both instructors, students, and curricula should always Keep our Eye on the Goal: Improve the Bottom Line.


Mufasa
(aka Dave of Sandy, Utah, USA)
[I can provide you with low-cost, remote Database Administration services: see our website and contact me via www.dasages.com]

 

[fumei]

One thing I always did when doing a Lab, even a small lab. I always walked through - afterwards - exactly what they did, and WHY they did it. It does not have to be a long review. For example, here is a review note for a Word VBA course I wrote and delivered.

Lab review: You created a procedure that runs automatically when a document opens. This is useful when you need to have action occur immediately, such as retrieve text or data from some other file, or collect information from the user.

You learned how to open a code module and change the view of procedures within a module.

You created another procedure and learned how to easily switch between procedures within a code module.

Knowing how to do this can be useful when a code module has many procedures and you want to be able to just edit one.

As for the point re: real-world examples. Spot on! This is a direct result of the first rule of technical writing (although of course it applies to all writing) - KNOW YOUR AUDIENCE.

If they are going to be real users of the system, then even if you have to fight for it, get some time to have real users actually use the damn thing. Sit and watch them. I can guarantee you will find you need to change something in the content of whatever you have already.

Gerry
My paintings and sculpture

 

[Gooser]

So, both instructors, students, and curricula should always Keep our Eye on the Goal: Improve the Bottom Line.

Both, eh?

--Gooser

 

[SantaMufasa]

Both of you, Gooser, should cut all the rest of me some occasional slack due to the many of my advanced ages.<grin>

Mufasa
(aka Dave of Sandy, Utah, USA)
[I can provide you with low-cost, remote Database Administration services: see our website and contact me via www.dasages.com]