Documentation – It Really Does Have Value
I installed some software this morning. Every indication is that it is just what I am looking for for a project I have in mind. It is touted as easy to use. There is source code available even. Supposedly there is documentation as well. But I can’t find the documentation. Now could I figure it out? Probably. I’ve been around code a long time and I can read the source code. I could probably duplicate this package from scratch if I really had to. But the thing is that I am trying to save time. The project is not a high priority but if I could put it together in an hour or two now would be an OK time to do it. Clearly though without documentation it will take longer than that. So I have moved on to other more important things like updating my blog. :-)
One of the things I have said for years as a professional developer and as a teacher is that “reading the directions is the short cut.” The older more experienced I get the more I believe that to be true. There are a couple of problems though. One is that too often documentation is non-existent or poorly written. Another is that even when documentation does exist people don’t want to read it. The latter is common with students and other beginners.
Why don’t they want to read documentation? Several reasons. Some people are lazy and just want someone else to verbally explain things. All too common in the classroom but you see it other places as well. How often have you opened a new game with a group and everyone wants someone else to read the directions and explain it to the group? One flaw here is that the further away one gets from actually reading and understanding for themselves the less they truly understand. And of course the “oh yeah I forgot to tell you about that” gotcha can make playing the game later interesting in unpleasant ways.
Other people try to save time by just starting in with what ever obvious, or apparently obvious, knowledge they get from looking at things other than the documentation. They’ll “figure it out.” Experience tells me that this is seldom a short cut and generally adds lots of time to the process. One may learn lots of things in greater detail but at that same time they’ll also learn a lot that is just plain wrong, inefficient, or miss things that will come back to cause problems later.
It’s hard to convince students of the value of documenting their own student projects because these projects tend to be simple and quite obvious. I wonder though if giving them a complex set of code and asking them to document it from scratch might be useful. One could grade them on how easy their peers found using the software after reading the student generated documentation. This is probably not trivial to set up but might be worth it. It is the sort of thing that influenced me a great deal.
When I was in university my professor handed me a deck of punch cards (I’m old experienced) that had no documentation and almost no comments inside and asked me to comment and document it. Talk about a life lesson! It forever convinced me of the value both of comments in code and documentation for software. The world would be a better place if more students learned that lesson. How do we teach them though?