There's an old joke among teachers that if you want to hide something from a student, stick it in a textbook. The 18 years I spent teaching at various colleges and the other 12 spent in the corporate training world have only convinced me to extend it to handouts, slide decks, most sentences not ending with "... and this will be on the quiz."
The flip side of that is that there are few places less conducive to learning something than a college classroom or a corporate training room. The only things you can guarantee are that everyone had trouble finding a parking spot, no one really wants to be there at that particular moment, and a significant portion of the class really needs to go to the bathroom.
I loved teaching and can honestly say the best part of the gig was the students. I still hear from many and I'm thrilled when I do. Students today have it far tougher than I did when I was an undergrad back in the early 1980s. I've never had time or patience for the "kids today are soft" stuff. Nowadays I tell people that I'm a freelance web developer when I have to be serious and when I don't I tell them I'm a professional cautionary tale. A lot of the work I do is related to the beer business somehow .
I really enjoy reading the tutorials published here. Even when it's a topic I'm familiar with I like to see how other brains make sense of them. The other day I came across a directory that held the website I used as a supplement for my last semester teaching basic web development. As I read through a couple of the pages I thought maybe ought to see the light of day again. The last university I taught at still hasn't killed the site, but it's really just a matter of time. My class was intended for students who weren't majoring in an IT-related field, so these are pieces that assume zero prior knowledge. I've never posted here before, so this seems like a good way to start.
So here's the plan: I'm going to take a two or three of the pages I wrote for my class and convert them to blog posts and post them here. There will be a little editing just to make examples less specific to the university I was at and just generally tighten things up (because there are no finished blog posts, only current drafts). Eventually they'll also make their way onto my personal site, but I haven't gotten around to really building that out yet (professional cautionary tale, remember?). If there's any interest when I've worked through the stuff I'm revising, I'm open to requests.
The first piece is going to deal with what is meant by "semantic HTML." Stay tuned.
Top comments (7)
You sound like a great teacher, Tom. And yes, I'm saying that in the present tense because you are clearly still a teacher! Thanks for the post.
Looking forward to reading more. Your students were lucky to have you!
You got me with the headline but I did read your post in full. I look forward to what you post next.
I like your writing style. Also reminded me of how good style (can) leads to good documentation. What's your view? I'm sure documentation was not a popular subject for students!
First off, thanks.
I've probably written 20 versions of this comment and then deleted them, illustrating better than anything else the challenges of any writing. Documentation is a big, huge, gigantic ball of pain and suffering that's great when it works and death by a thousand paper cuts when it doesn't.
To me, the best documentation has a point. There's a reason it's there. It tells me what that reason is right up front, then, in the fewest words possible, it actually does that thing. Then it stops.
It's easier said than done, of course. It's about as much practical use as the old joke: "Want to be a millionaire? Great. First, get a million dollars..."
I never really spent that much time on documentation because the thing most students had a good grasp on was "I don't want to be here and I'm afraid of making a mistake and looking dumb."
When I had to write multiple-choice test questions I always made the last choice a joke answer because test anxiety is a real thing and I figured if I could get them laughing it might make them forget to be nervous. After a while I just sort of extended that into all of my teaching. And so it snuck into my writing.
I prefer the joke "How do you get a small fortune?" Start with a large one.
Yes, documentation is hard, often harder than writing code. What does this do? What are the restrictions on arg x? Where does this method fit in a workflow?
Great idea! Thanks!
Nice
Some comments may only be visible to logged-in visitors. Sign in to view all comments.