If you’ve ever done any computer programming, the following should probably have a wake-up warning:

“I don’t need to add comments to this code. It’s obvious what it does!”

For the non-programmers among you …

Computer code is difficult to read. Not because it’s a seemingly arbitrary sequence of gibberish, that’s part of it, but you get used to it. No, the problem is that each line, each word, each symbol has a precise and logical function.

Swap a plus sign for an ampersand and you completely change the program.

This makes it difficult to read because you need to go character by character, thinking about what it all means. You can’t always skim the code to understand it.

Even if you wrote the code a few months ago, it can be like hieroglyphs.

That’s why not crazy programmers add comments – little descriptions that explain what each piece of code does and why.

It can make your job ten times easier.

If only course designers had the same discipline …

I once inherited a course on a subject that I knew a little about, but was not a practitioner. The field was a radioactive football, being kicked from person to person, without anyone wanting to take responsibility for it.

It landed on my lap a week before I was due to introduce it.

(In that sense, I was lucky. It wasn’t just a few hours! Ugh!)

Except these slides were complete gibberish.

One of them had a title … I forgot what, but it was something like “Don’t do this.” On the slide was a picture of a rowboat.

And in the notes section?

“History of the Canadian Ship”.

This was a complete module on its own, so I couldn’t use the surrounding slides as context.

There were no learning outcomes, no instructor guides, nothing.

I did not know this story or what it was supposed to convey.

That was the worst slide, but at least half of them made no sense. They would have four vignettes that had something to do with something, I suppose, with a comment underneath that could have referred to a completely different slide.

Even with the tight time frame, it was easier to rebuild the field from scratch than to use this festering pile.

Wish I could say that this stood out because it was so unusual. Is not. One of the many nightmares of bad PowerPoint presentations is that experts throw something on a slide and rely on their memory to add stories, context, and exercises.

People often hate working with me on their courses. They want to dive in and ride the slides and exercises. I always insist on creating learning outcomes first, then developing a plan, and then documenting everything as you go.

Those people might hate it, but the people who inherit the courses love me for it.

Be like me: get the course out of your head and into the documentation.