Monday, February 11, 2013
The Importance of Good Documentation and Instructions
As I’ve mentioned repeatedly, I write technical documentation and instructions–I teach people how to use computer programs.
Which means that BAD documentation and instructions make me want to hurt someone.
I’m trying to become familiar with the new online course management system we’ll be moving to, and after a several hours of this, I’d like to take their entire support staff and beat them senselessly.
My goal: to import questions from a text file of some sort into the program.
What I found first:
A very long list of instructional videos. I would rather eat lint WHILE being stabbed with a fork than watch instructional videos.
Because they are almost always a WASTE OF MY TIME.
I finally find a help document.
Completely worthless.
What I found next (within the program):
OK. Fine. I made a text file.
It failed. Repeatedly.
What I finally find after several hours of wasting my time.
Really. Why does the help that pops up WITHIN THE PRODUCT not mention those parentheses? This is a system used across the country–in fact, I believe it’s one of the most used systems. So why are their help files so abysmally NOT HELPFUL.
WHY CAN’T THEY JUST GIVE ME A CLEAR, HELPFUL EXAMPLE?!
Now if you’ll pardon me, I’m going to go try really hard not to put my fist through my monitor.
ADDENDUM the FIRST:
OK, trying to fix my text file, and I’m now even MORE confused. I really hate technology.
ADDENDUM the Second:
Co-worker looked over everything with me, and we can find no reason why most of the file is failing.
Have I mentioned how much I hate computers?
February 11th, 2013 at 4:09 pm
I feel your pain. Of course it makes sense to the people who write the help documentation, because they already know how to use the program.
February 11th, 2013 at 6:54 pm
Oh, you’re trying to use Blackboard. I’m sorry, Michelle. Really and truly sorry you have to deal with that time and money sink. We have that at the community college I’m going to. Aside from reporting grades (which is iffy), and dissemination of PDF files for classes, IMHO, it’s pretty much worthless. Although the administration is now FORCING the instructors to use it (many of them don’t want to waste the time, and after trying it once, want nothing to do with it).
Just over this weekend one student was taking a quiz online, and the timing function didn’t work. The rest of the class liked to jump on the fact she was using Safari and that was probably the problem. Well, I used Safari to take my test and it worked just fine (for as well as Blackboard “works”, seriously that quiz function sucks, it’s confusing and I’ve been using computers for 30 years now). My guess is it was another bug showing up.
February 11th, 2013 at 7:06 pm
Well, the system we’re using will no longer be supported, so we have to move. And none of the other options are any better.
I think that *all* online classroom systems have issues. I’m hoping the things we use will not be problematic.
Since I’ll be supporting it next year, I really really hope we don’t have this may problems.
February 11th, 2013 at 10:13 pm
I can’t tell you how much documentation I’ve created for clients for software that has documentation, but the documentation sucks. Although I’ve seen cases where the documentation was fine until the program was updated, and someone in management decided it wasn’t important to update the documentation because “the changes weren’t that significant.” Except they were.
February 12th, 2013 at 10:45 am
You don’t hate computers, you hate computer *programmers*. I reminded of a poster of corollaries to Murphy’s Law we used to have in the lab. One read: “If builders built buildings the way programmers write programs, the first woodpecker to come along would destroy civilization”.