How to develop training when the subject is a moving target?

Recently, I received this question from someone who had read my book on Writing Successful Software Classes. My answer appears after his question:

Problem: They keep changing the software spec's, as I'm developing training!

> The company is
> currently in the process of creating and implementing a new core business operating system.
> Our legacy system is antiquated to say the least (it is DOS based).
> The new system is being built from scratch, so this is no out of the
> box ERP that we are talking about.
>
> My team and I are competent instructional designers and trainers but
> our experience is limited to training on processes or systems that are
> already complete. What I am struggling with is building training for a
> system that is being built as we are expected to develop training. If
> the system were complete and then we had 6 months to develop the
> training before it was implemented, we would be okay, but that is not
> the case...we are expected to develop training from
> Functional Design Documents which by the way are not necessarily
> well-written. The system is being given to us in milestones, but they keep changing things and changing the milestones.
>
> I have found resources on major software rollouts, and systems
> implementations, but they are very technical in nature and gloss over
> end user training. Other resources that do concentrate on technical
> training make the assumption that a system or concept is complete when
> you develop the training.
>
> Do you have any advice or ideas of how we can tackle this? Let me know
> if you want any more details. I really appreciate your thoughts and your time.

Solution: Focus on documenting business processes first, then write keystrokes-and-clicks second

Training and user documentation almost always comes at the end of a software rollout. By the time the trainers and technical writers have the information we need, almost everyone else has finished their part of the project. And when people at the beginning of the project take more time than planned, and the deadline stays the same, that extra time they get must be taken from someone else. Usually, that's the trainers and technical writers. "We allocated three weeks for you to develop training, but testing and bug fixing took an extra week, so we had to shorten your time to two weeks."

At most companies, this is just the nature of the job. There are ways we can adapt.

First, focus on writing good instructions for your users. Unless your users must perform their work without referring to a manual, the instructions will be the user's safety net when they need to begin using the software.

Research I've done among the users that I serve showed that they prefer printed instructions. They don't like switching between two windows on their computer screen: one with instructions and one with the software. Among my users who have dual monitors, that is not a problem. But most of my users have a single, 17- or 19-inch monitor. I suspect that is why they prefer printed instructions.

Notice that I've been using the term "instructions" and not "user manual." A user manual is more than a collection of instructions. It gives background and context to the instructions. That is, a user manual doesn't just tell how to perform tasks, but also when and why. Think of instructions as a series of cheat sheets, or quick reference guides.

As you're writing those instructions, you will be simultaneously developing the demonstration that you use for training. More on that later. (At this point, you were probably wondering when I'd get around to answering your question about developing training. Hang in there).

Our biggest challenge is that as we are writing user instructions and developing training, the software is changing. We need to document and develop training for a moving target. How to do this? Here's something that has been key for me: start first with the information that will not change.

Forget about beginning your writing and course development with the introduction, or the clicks and keystrokes. Instead, begin with the information this is most unlikely to change.

In my experience, the specific list of business tasks that users need to perform with the software is unlikely to change. So I start with that. For example, suppose the business tasks I must teach are:

1. Create a new customer.


2. Enter customer demographics.


3. Attach a mortgage record to the customer.

Each of those tasks will have a quick reference guide, and a demonstration in your training class.

Now, I understand that you do not yet have the keystrokes for performing those tasks. The software is changing, so you can't write the keystrokes and clicks yet. But there are some things you can write about each of these tasks, such as:

• When to perform this task (where does if fit into your workflow?)


• Why to perform this task (what deliverable is produced; what result?)


• Next steps (what do you usually do next?)

So on each of your quick reference guides, you can add that information. For example, for the task "Create a new customer" your quick reference document might look like this:

Section: Creating a new customer

Subsection: When must you create a new customer? [This is business process information. You should be able to write this even if they don't have the software finished]
Subsection: When How to create a new customer [This subsection isblank, you don't have the keystrokes and clicks yet because they keep changing them on you]
Subsection: Results [This is business process information. You should be able to write this even if they don't have the software finished]
Subsection: Next steps [This is business process information. You should be able to write this even if they don't have the software finished]

Notice in that example above, you can write three out of four subsections even while the software is still being changed.

Remember I said that you can simultaneously develop the training demo? So at the same time that you start writing these instructions, you can start writing the slideshow for class. Your slides might read something like this:

Slide 1: Creating a new customer
When must you create a new customer?
Create new customer only when...
Slide 2: Demo
...blank slide, here you begin your demonstration...
Slide 3: Results
A new customer record in....
Slide 4: Next steps
At this point, you can now do this....

You can also start writing the in-class exercise, if there is one. For example, "Create a new customer using the following information..." During the exercise, you would have the students try to perform the task, using the quick reference guide that you wrote.

At this point, you send the instructions back to the subject matter experts for their sign-off. Since you don't have the keystrokes and clicks yet, you probably won't be sending the material to the software guys for sign-off.
But what you do have is the business process information, that is, what the user will do and where that fits into their workflow. So you will send this to the business owner of the software.

As the software team finalizes the screens, you'll be able to fill in your instructions with the keystrokes and clicks. You'll also be able to plan your training demos. When all those instructions and demos are filled in, you have most of a user manual and a nearly complete training course.

When you train, you'll make it clear that you don't expect the people in class to come out with the keystrokes and clicks memorized. That is what user documentation is for. Instead, your purpose in class is to:

• Show the students where each task fits into their workflow.


• Emphasize the critical steps in each task: things you must do.


• Stear them around the mistakes that you cannot recover from.


• Show them where to get further help with the software (if your company offers this kind of support).

In your email, you mentioned Functional Specification documents. You might be able to pull much of this information from those documents. But don't get bogged down in trying to write detailed instructions from those functional specs. It just isn't realistic to document clicks and keystrokes until you have a working product in front of you, and an authority figure who says, "freeze this interface here." Until then, you are writing the framework, or outline, into which you will drop these keystrokes and clicks.

This is the process that has worked for me. I hope that you will find it useful. If you have any questions, I'd be happy to help.

8 Tips for Improving Your Technical Writing (guest post)

Good technical writing is always clear, practical and tailored to a specific audience, be it a technical or non-technical audience. What separates good technical writing from average technical writing, however, is taking the time to make the written material as user-friendly as possible. Here we will explore 8 tips for improving your technical writing.

1.) Break up text under clear headlines and subheads.

Technical writers are familiar with using headlines to transition from topic to topic when writing material. What often gets forgotten is effectively using subheads to further break down the material. Most technical readers strongly prefer to cherry-pick the specific information they're looking for, and the frequent use of headlines and subheads allows them to do this with ease. For non-technical readers, there's nothing more intimidating than large blocks of text with no place to rest the eye. You'll find that breaking each topic down into small, manageable chunks will also aid you in the writing process. Writer's Digest recommended revisiting your headlines to make sure they accurately summarize the content of that particular section.

2.) When possible, break up text into brief lists.

Not everything technical can be broken down into a short, snappy list some individual steps involve numerous vital details. However, if you can lay out a list of steps before plowing through those details, you'll let your readers know early on that there's an end in sight and logical steps to get them there. Lists also create a break for the eyes.

3.) Keep your tone professional.

Technical writing is not prose or creative nonfiction. It is written only to teach a reader how to do something or how to use something. While the For Dummies books exemplify a move toward technical writers creating more folksy and conversational how-to material, most technical readers aren't looking for clever wording or side stories while they read. They want stripped-down, straightforward writing that will help them learn how to accomplish a task. This doesn't mean you can never include clever and related anecdotal elements; it only means that technical writers should use them sparingly, particularly for a technical audience.

4.) Use present tense and imperative sentences.

Readers want to be told implicitly what to do. Writing imperatively and in the present tense is not only helpful to the reader, but it also eliminates unnecessary wordiness. For example, "Select Menu, and choose from the available options" works better than the more conversational "Once you've found the menu, you can choose from the available options."

5.) Keep it simple.

When you're proofreading your writing, keep an eye out for big words that take away from the simplicity of the material. While some jargon is unavoidable, you can certainly substitute "use" for "utilize" and "end" for "terminate." You're not trying to impress anyone and simple words are often just as effective as more elaborate words. Also, try to break up compound sentences whenever possible into two simpler sentences.

6.) Use specific words.

Part of using specific words involves avoiding the word "it," even on the third and fourth reference. Readers need to know what "it" is throughout a specific section to avoid confusion. You will also need to use consistent terminology. Do not alternate the terms you use to add variety to your writing.

7.) Write in active voice.

Using imperative sentences whenever possible will help you avoid the passive voice most of the time in instructional material, but for other technical writing you will need to actively avoid the passive voice, which will not only make your material more wordy, but will also weaken your sentences.

8.) Ask for feedback.

Some supervisors are better at giving feedback on your technical writing than others. You may need to ask specifically for them to look over your work and point out any consistent weaknesses in your writing and areas where you can improve.

About the Author

This guest post is contributed by Angelita Williams, who writes on the topics of online courses. She welcomes your comments at her email Id: angelita.williams7 @gmail.com.

Slashdot Review of Magento 1.3 Sales Tactics

Slashdot reviewed my latest book. Check it out.

Converting a Course from Classroom to Online

I'm working with a client who is converting a classroom-based course to an online course in Moodle. I'd like to share a question that I received from the client, and my response. I've edited our exchange to make the client anonymous:

Question

I hoping you can help me clarify a few issues before [our e-learning team meets].

The plan now is to take the existing ... Curriculum and "translate" it to Moodle. I am finding this to be a very difficult and awkward process. I'm thinking that this is a bit backwards, and that developing an online course requires building from the ground up. Its not that all of the content must be rebuilt from scratch, but that the order of material, the grouping of concepts, and flow of the online course is going to be different than a traditional class room experience.

In your experience, do you think that my instincts are correct here?

My Response

Yes, I think you are realizing one of the key facts about porting a course from classroom to online. Bringing a course on-line often demands that you change the organization and timing of the course.

Breaking down the classroom course into its smallest logical chunks is a good start. It's easier to rearrange small chunks than large chunks. If you find yourself rewriting most of the material, then you've broken it down too far into chunks that are too small. The idea is the break it down without needing to rewrite.

You will also need to allow more time for online learning. In a classroom, because of the force of the instructor's personality and the quick, live interaction with the instructor, a student can usually cover material faster than in an online course. The only time I have found that to be untrue is when the classroom presentation must be slowed down to accommodate slower students. But in a small class like you are accustomed to teaching, when you have everyone "in sync" and focusing hard, students can assimilate an amazing amount of material in a short time. Students won't have that experience on line. So when you bring the course on line, you must allow more time for each topic.

On line, you need to make everything the student learns relevant and useful, as quickly as possible. Again, you don't have the force of the instructor's personality helping the student to wade through preliminary material. There's no one there to say, "Stay with me, pay attention to this next part, because in an hour you're going to need to know how to do this." So to keep the student motivated, before you make the student learn something, show how that piece of knowledge will help the student to perform the task you're teaching. If each topic in the course is a separate competency, for each activity that you make the student perform or each resource that you make the student view, state how it will help the student to develop that competency.

On line, you need to test and apply the student's knowledge as soon as the student gets it. Moodle's quiz feedback is a great tool to combine testing and learning. You can give feedback for each individual answer that a student selects, telling the students why it's correct or incorrect. You can also give feedback for each question, regardless of which answer the student selected. Use this to explain the relevance of the question, or to give hints that will help the student to remember. For more about using Moodle quizzes as a teaching tool instead of a testing tool, see my blog post here: http://williamriceinc.blogspot.com/2008/03/using-different-kinds-of-feedback-in.html.

And after you've confirmed that the student knows the material, you need to have them apply it as soon as possible. Having the student create something and upload it to a Moodle assignment or forum are the standard choices.

As for rearranging concepts, you will often need to do this. If several parts of a course, or if several courses, depend upon a student understanding a concept, you can always link back to where that concept was introduced. When the student needs to remember a concept before learning a topic, at the beginning of that topic, give the student the chance to review the concept. If the student is comfortable that (s)he learned it well enough the first time, the student can skip the review. If not, the review is there.

Also, while teaching conceptual (theoretical) information, relate the concept back to the competency. The student might think, "I just want to learn how [perform this task]. Why am I learning about [this conceptual information]?" If you can't state how a concept relates to the competency, then try this: break the concept down further, into smaller pieces. Can any of those pieces relate back to the competency? If so, teach just that part of the theory and leave the rest out.

So on line: your presentations will be shorter, you will insert more teaching quizzes and short assignments, at the beginning of each presentation you will motivate the student by showing how the material helps build the competency the student desires, and before teaching anything theoretical or conceptual you will state how it helps the student perform the competency they are developing. These are all things that you do naturally in front of a classroom, but now you need to do them explicitly on line. So it's not just a matter of taking the written course material and popping it into an online course. You must also take the pieces of yourself that you give a classroom full of students, and put them on line for your remote students.

Client's Response

Perfect. You confirmed all of my suspicions. We met today, talked about all of these issues, and now finally have a plan for moving forward that makes sense. We have some cool ideas to add our own flavor to all of this. We'll be sure to show you what we have once we have some of our first beta topic together.

Example of Using the Same Product Characteristic for a Category and an Attribute in Magento

This question came from someone in Iceland. It is a good example of how to use a category and an attribute, for the same product characteristic.

The administrator wants to enable customers to sort shoes by style, and then drill down into the size. He also wants his customers to be able to start with size, and then see the styles available. I have edited the original question and my answer for clarity, but the content is the same.

Question

Hello.

I have been reading your book - the first chapters. It has FAR better descriptions then the magento user manual...

Here is the setup I will be using:

I will have 2 stores (to begin with).

Store1 will sell clothes and Store2 will sell shoes.

What I am trying to figure out is what to do with attributes for shoes - I would add color to them and some other attributes.. But should i add Size to them as an attribute? Almost all our shoes come in the same sizes. So if a user clicks the size in Layered navigation the will show the customer all shoes we have anyway. What i need is for the customer to be able to click a size and then magento will show them all shoes that we have size and are also in stock. Say a user selects size 39 - the website should only show shoes that we still have in stock in that specific size... is that possible ?

I know i must add each shoe as a configurable product and then simple products for each size of that shoe (because i want to count stock on each and every size)

Regards, Hedinn

Answer

To enable customers to sort shoes by style, and then drill down into the size:

1. Ceate a category for each style, such as high heels, pumps, sandals.
2. Then, create an attribute for the size of the shoe. Make that attribute filterable in the navigation menu.
3. For Position, enter 0 (zero). This will place Size at the top of the layered navigation menu, on the left side of the page.

Your customers will select a category to see the style of shoe they want. After they select the category, the layered navigation menu will display on the left side of the page. They will see Size at the top of that menu. Now, they can filter that shoe style by size, and see only their sizes.

To enable customers to see all shoes in their size:

1. Create a category called Find Your Size.
2. Put every pair of shoes that you have into that category.

Then when the customer clicks the Find Your Size category, she sees the layered navigation menu on the left. Remember, Size will be a filter at the top of that menu.

By the way, you're the first person who has written me from Iceland. Cool!

Regards,
William

Magento Question About Applying Sales Tax Based on Amount of Purchase

I received a question about how to configure Magento to apply sales tax to only purchases that are above a speficied amount. The question and my answer are below.

Question

Hello William Rice,

Ref Article: http://www.packtpub.com/article/creating-tax-rules-in-magento

First of all your article is really cool and help full. I gone through all the steps, but i'm unable to figure out how to set TAX based on Product cost?

I'm interested to learn how can we define TAX based on 'The amount' of the purchase. For example, some places tax clothing purchases only above a specific amount.

Criteria is like this:

• TAX should be calculated if Product cost is higher than 150$.


• if Product cost is less than or equal to 150$, TAX will be ZERO.


• TAX Rate is 5.50%.

Could you please guide me how can i implement above criteria in Magento?

Thank You,

-Shahil

Answer

Shahil,

The most expedient way to apply a tax rate based upon a product's price, is
to create a product class for the products in that price range. In your
example, you would need to create a tax class for those items, such as
"Clothing items costing$150 and above." Then, you would apply that tax
class to all of the clothing items costing $150 and above.

This means you would need to search through your catalog, find every
clothing item that costs $150 or more, and apply the product class to that
item. To find all these items:

1. Go to Catalog > Manage Products.


2. The top row of the catalog listing, the one that is shaded in blue,
   is for your search criteria.


3. For Price, enter From 150 To a very large number.


4. You might also use the Attrib. Set Name field to find your
   clothing. It depends on how you have your catalog set up.


5. Click Search and you will see the results.


6. Using the check boxes to select all of the relevant clothing
   products.


7. From the Actions drop-down menu select Update Attributes. Then
   click Submit.


8. This brings you to an Attributes page. Whatever you change and save
   on this page, happens to all of your selected products.


9. Select the tax class "Clothing items costing$150 and above."


10. Save.

Note that when you change a clothing item's price, you'll need to also check
its tax class. This will just need to be part of the store admin's job. We
all would like to see functions like this automated, but until Magento lets
you include the price in a tax rule, this will require intervention by the
store administrator.

Hope this helps. Good luck in your e-commerce endeavors.

Regards,
William Rice

Magento 1.3 Sales Tactics is Published

My new book, Magento 1.3 Sales Tactics, has just been published by Packt Publishing. My goal for this book is to help you solve real-world Magento sales problems with some simple, effective recipes. You can read a sample chapter on the publisher's website. It's too new for any reviews yet, but the CEO of Magento recently received a copy, and I'm eager to know what he thinks of it.