Mixed up Policies and Procedures

The terms policy and procedure are often used interchangeably. The two types of information are also often mixed up in the same document, which doesn't help the reader understand the rules and practices of the organization.

Policies are the business rules and guidelines that are the basic operating principles of a business. Policy documents spell out those rules, focusing on general principles and the rationale behind them.

Procedures are the specific steps taken to accomplish a task. They spell out the who, what, when, and where in great detail. Procedures are the practical implementation of the abstract policy.

Here's an example of a bank's policy and procedures:

Policy: "We do not lose our customers' money because of carelessness or malfeasance."

Related Procedures: There will be a number of procedures for taking in and giving out money in a bank account. There will be other procedures for making sure that bank employees can't get their hands on the money. These procedures will detail who does what when, what computer systems and other records they use, and what controls make sure these procedures are properly carried out.

Keeping policies and procedures distinct, either in separate documents or separate sections of one document, gives your readers and your auditors a clear picture of how and why your business functions.

Posted in Uncategorized | Leave a comment

Training You Have To Do / Want To Do

Most of us take “mandatory” training on the job. Most of us also do voluntary training—either at work or on our personal time. You know the difference in how you feel about these two experiences. You put off the mandatory compliance training and approach it with annoyance. You look forward to your French Cooking class (yes, it’s training too) and wouldn’t miss it for the world. Maybe you also take voluntary training at work in some skill you want to acquire, and that is something you enjoy doling.

OK. It’s not possible to make every work-based training as exciting as learning to scuba dive. But maybe it is possible to motivate your learners and get them try to get something out of the experience instead of just endure it.

One way to do this is to make the training as relevant as possible to the learner’s work. Instead of starting out with a list of what you’ll learn and how important this is to the firm, set up a challenging situation that the learner might encounter on the job that requires the skills that will be covered in the course. Then have the learner anticipate what they would do in the situation.

  • The course covers Excel. Start with the real-life challenge of presenting financial information to your CFO in order to try to stave off a budget cut next year. What information could you present and how would you use Excel to put it together in a persuasive presentation?

  • The course covers compliance rules on information walls in a financial institution. Start with the scenario where you hear about a potential merger involving a client. What actions do you take; who needs to be told and what do you need to tell them; who cannot be told, and so on.

Don’t give any feedback on the learner’s responses yet. Let them go through the course. At the end, present the challenge again and have the learner see if her or she would now respond differently or more completely to the challenge. You will have made the learning at least relevant to the user and perhaps made them approach the training with a sense of positive anticipation!

Posted in Uncategorized | Leave a comment

Training Wheels and Skinned Knees

Remember how having that set of “training wheels” helped you learn to ride your two-wheeler? Or maybe you just learned by grit and determination and skinned knees. Those two choices apply in learning a new piece of software too.

  1. Get formal training in the new tool—go to an instructor-led class or take an online course. –That’s the training wheels approach.

  2. Jump in and try it out yourself.–That’s the skinned-knee approach.

For the learner, the two methods work best in two different situations. If you are learning a new photo editing system when you already know another system well or learning a new release of a familiar product, try learning on your own. When you are learning an entirely new type of software, take some kind of format training.

How does a technical writer support these two very different learning approaches?

For the learner who wants training wheels, we excel at creating courses. So that is pretty much covered.

But for the software explorer, we need a new approach. Think about where someone is going to topple off the bike, and try to supply help for that specific problem. Some ideas:

  • Popup help triggered by the old command to show the new one.

  • Quick tours that point out the areas worth exploring so the learner doesn’t miss any feature.

  • FAQs—the old tried and true approach works.

  • Targeted training modules focused on the very narrowest topics.

Posted in Uncategorized | Leave a comment

Attention Deficit

Sometimes it seems that everyone is so distracted and busy that we all have ADD. Technical writers have a number of tricks to get information across to people who are perpetually pressed for time.

  • Chunk information—take a large body of information and break it down into bite-size bits of related material. Then present those chunks in a way that separates them visually as well. Use headings and white space to break up information into manageable segments.
  • Use the old classics—tables and bulleted lists. They preprocess information for readers so they can quickly locate what they need.
  • Break the material up into several smaller documents, each of which focuses on just one key area.

If you try techniques like these, you can get and hold the reader's attention.


Posted in Uncategorized | Leave a comment

Reinventing the Wheel

Most complex software development projects have a number of related pieces of documentation:

  • End-User documents such as user guides, quick reference cards, training guides
  • Business documentation: business case documents, project updates, etc.
  • Technical documentation: requirements, design documents, operations manuals, etc.

Sometimes it feels as if you are writing the same thing over and over for different audiences and purposes.

Instead of starting fresh each time, leverage what is already there. Now, that’s an obvious solution, but it can be harder to do that might first appear. When different people write materials and when a project goes on for a period of time, it’s easy to lose track of what is available and end up recreating it. Keep a master list of documents with their contents. The time it takes to do that pays off when you can find the information you need already written and ready for you.

Even if you don’t have a master list, here are a few tips to help with documentation on a typical software development project:

  • Look for procedures in user guides and reword them for training materials and presentations. You can use them for test cases as well.
  • Use the requirements as the source for things like lists of statuses, properties of fields, names of screens. You may need to update the requirements as things change during implementation, but again the time is worth it.
  • Leverage the business case for internal and external marketing materials.
  • Create PowerPoint presentations from diagrams and text in other business documents; just turn the text into short bullet points.

Before you plunge into a new document, always take the time to see if you or someone else has already invented that particular wheel!

Posted in Uncategorized | Leave a comment