Monday, November 25, 2013

Teach, Don't Tell

Think about the work you and your colleagues do every day. We support the technology for our campuses; each of us "owns" a small part of the whole. You should know intimately how to do you job. But consider for a moment: what would happen if one of your colleagues disappeared and you needed to fill in? Maybe it's an extended vacation, or a sudden illness. Perhaps that person has retired, or moved to a new organization. Do you know what they did? Could you adequately fill that position, at least until someone more permanent could take over?

An important part of our jobs is to create documentation about the functions that we perform. Some folks consider no documentation as a form of job protection, but it really isn't. Managers often view someone who does not document their work as a liability. Those who fully document what they do often rise in the organization.

But how can we effectively write down how to do our tasks, in a way that makes sense to someone else? Sure, it's easy to describe your functions to yourself; you already know how to do the job. It's much harder to adequately define how to fulfill your roles and responsibilities to someone who hasn't done it as their day-to-day job.

As Steve Losh describes, the answer is Teach, Don't Tell. From the article:
If you want to take a person who has never played the guitar and turn them into a virtuoso guitarist, how can you do that? 
You teach them. 
If you want to take a high school student and turn them into a computer scientist, how can you do that? 
You teach them. 
If you want to take a programmer who has never seen your library before and turn them into an expert user of it, how can you do that? 
You teach them!
If the goal of documentation is to turn novices into experts, then the documentation must teach. You should think of your documentation as a lesson (or series of lessons) because that’s what it is.

The process needs to go something like this:
  1. Figure out what they already know.
  2. Figure out what you want them to know after you finish.
  3. Figure out a single idea or concept that will move state 1 a little bit closer to state 2.
  4. Nudge the student in the direction of that idea.
  5. Repeat until state 1 becomes state 2.
If you have ever taken a "CMR" (Communications, Media, & Rhetoric) class at Morris, you should recognize the process as rhetoric, which makes a good framework for any written material where you need to move your audience towards a new idea or concept. This is a long but very readable essay on how (not) to document computer programs. Use the same guidelines for documenting any process.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.