News

This post is part of an ongoing series.

After spending six hours or so on class prep Monday, I ended up canceling class yesterday with the following BlackBoard announcement:

Your professor has granted himself an excused absence for sickness today.

Thursday is Fall Break, so Week 7 will go down in the annals of history as one of the three least interesting weeks in this sixteen-week semester. Or maybe one of the five, depending how well the students do on their presentations….

More next week.

This post is part of an ongoing series.

Week 5
Week 5 doesn’t get its own post, because it would be terribly uninteresting. I gave them the day off last Tuesday so that they could work on their semester projects. I did still require them to turn in their proposals before the class’s regular start time (by email), and I did still give them document assignments on both Thursdays. The first was some practical instruction on building a rudimentary, styled layout, and then filling in the paragraphs with your actual content. The second took that concept a step farther and built an actual Word template with custom styles.

Anyway, since we didn’t meet in class it apparently lifted the Curse of Mr. Pogue. I didn’t hear news of any life-altering drama that afflicted my students during week 5.

Life-Altering Drama
Week 6 was another matter entirely. We got the Swine Flu! Or technically (as I’m told), Novel H1N1. Anyway, OC canceled chapel this week in an effort to stem the spread of the disease on campus, and still I had two students miss class because of it, and another who left early (sniffling) for a doctor’s appointment.

As a deeply-concerned educator and a compassionate human being, I really hope these disruptions stop happening. As a storyteller, though, I’m anxious to see what’s going to befall my class next week. I’ve got sixteen students, and the class is sixteen weeks long. So far I took the bullet on week 4 (when it was the early birth of my son that interrupted class), and week 5 was a bye, but week 6 hit three students at once. So we’re still on track for the rest of them to get one event per week. I’ll keep you posted.

Handbook of Technical Writing
So I started my class by stepping out from behind the computer station and holding up a magnificent reference text, Handbook of Technical Writing, vol. 9. I showed it to the class, and said, “How many of you recognize this book?”

I got three or four raised hands. In the back corner, someone asked timidly, “Wait…is that the textbook for this class?”

I showed my teeth, in something like a smile. I asked, “How many of you have read anything in it?” One of them said he’d glanced at the section on copyright, out of curiosity. I shook my head sadly, and then I laid down the law.

Every one of the tutorials I’ve provided starts out with a list of “related topics,” which are section titles straight out of the handbook. It’s usually 6-10 pages worth of material, and I always read through those sections before writing my tutorials, so that I’m not repeating information. That means there’s some important technical information in there that’s the students aren’t getting if they’re not reading it.

And, I pointed it, it’s information that I’m going to expect in their papers when I grade them. If it comes to it — if I find myself having to hand out Cs and Ds because nobody’s reading their textbook, I’ll start having weekly reading quizzes. I don’t want to do that, because this isn’t information that needs to be memorized — rather, they need to know how to use the textbook as a reference. They need to get a feel for what’s in it, and how it’s organized, so they can go look stuff up when they need it. I deliberately picked a cheap reference book instead of a big expensive textbook so that they would keep it at the end of the semester, and have that info handy.

So I did my best to express that, and pointed out (by way of example) that none of the multi-page proposal memos they’d turned in had used a header on the second page — something explicitly stressed in the textbook. I saw some sheepish faces at that, but I’m not grading that one against them, because I hadn’t actually taught them how to do headers yet.

Document Headers, Page Headers, and Section Headings
One of the confusing aspects of technical writing, I admitted, is overlapping terminology. For an industry built on clarity of expression, technical writing certainly accepts its share of confusing expressions.

In their first tutorial, I introduced the students to the standard business letter header (which might be a stylized letterhead, or it might just be the sender’s contact info). Then the next week I showed them the standard memo header (which consists of four fields: To, From, Date, and Subject). I also asked them to divide their first memo into several sections, each labeled with a heading. Then this week I started complaining that their documents didn’t have headers.

For clarity, I refer to this last kind of header as a “page header” (since it essentially appears on every page in the document), and that first kind of header as a “document header,” since it only appears once at the top of the document. Actually after business letters and memos, the document header is mostly replaced by title pages, so it doesn’t matter.

Still, there’s room for confusion. I apologized for that, spelled out in detail what each of these elements is, and told them the trick to keeping it straight is learning the purpose of each element rather than its name. Because they serve clearly distinct purposes, and in context it’s almost always easy to recognize which one is under discussion at any given time.

Introductory Paragraphs
Context. That’s a word that’s come up again and again in the last few weeks. In their proposal memo assignment, I told them exactly which sections they needed to include: Introduction, Scope, Methods, Timetable, Qualifications, and Conclusion. I also reiterated from previous tutorials that every document should have an introductory paragraph. One of my students wrote me during the week to ask if I intended the section labeled “Introduction” to be the introductory paragraph (ah, these overlapping terms again…), and I wrote back that, in fact, no I didn’t. I sent that reply as a general email to everyone in the class, but still I got proposals that went straight from the document header into the section heading “Introduction.”

So I took the chance to clarify that for them. The purpose of an introductory paragraph is to introduce the document that follows. This blog post starts with the simple, “This post is part of an ongoing series.” That’s not terribly telling, but it gives you some context. If blogs weren’t inherently sequential, I would feel a much stronger need to tell you, in each post, why I’m writing that post.

Memos aren’t inherently sequential. Most technical documentation isn’t. Emails can be (specifically when they’re replies), but most written communication ends up living a life of its own as an independent document. And, most importantly, it doesn’t die. Long after you’ve forgotten about it, long after you lose track of why you asked your boss for two hours’ leave in the middle of the day, the document you used to request it is still readily accessible.

More than that, it’s reusable. I left aside their proposal memo and turned to email, because it makes the point more effectively. Email is something we do so casually, every day. Half the time, even business emails are just a matter of the guy from the next cubicle asking you to send him something in writing so he can remember that thing you discussed at the water cooler. It doesn’t need to be anything more than, “Hey, remember that you agreed to review that document before Friday. –Aaron.” We all get in the habit of jotting off quick emails.

Documents that Live Forever
The problem is, even if you know this email only needs to get to the guy in the next cubicle, and only needs to live until Friday, it sticks around. And the Forward button becomes the easiest and most dangerous thing in the world. (That comment got a laugh.) I told them that I’d written hasty little reminders like that to my coworkers that came back to me, years later, and somewhere in the list of people who’d replied in the meantime was the Secretary of the Department of Transportation. Somebody needed my opinion to back up a claim they were sending to Washington, so he forwarded my email on up the chain and I got it back long after I’d forgotten all about the project under discussion (let alone that particular opinion).

I was in the clear, though. I did get brought back into the conversation, but I was able to participate because I’m a good technical writer. Even my quick reminder email included enough of an introduction, enough context that when it popped back into my inbox my own message brought me back up to speed.

Preserving Context
That’s exactly what documenting code is for, so I wasn’t surprised when the concept resonated with my class. It’s not an obvious concept, though. When you sit down to write a document, that’s all you’re thinking about. Why you’re writing this document is so abundantly clear, you can’t imagine a time when you would look at this document and not know what it was for. Writers run into this all the time when they try to write the cover letter to submit a novel to an agent or publisher. If I — a writer — am writing a letter to a literary agent, isn’t it obvious that I’m writing to ask him to represent me? Why do they want introductory paragraphs? Why do I need to come up with some clear way of saying, “I’m writing to ask you to represent my novel.” Shouldn’t that be obvious?

The thing is, that’s all dependent on information I have. I am a writer, and I’m writing to this person as a literary agent. I could be a salesman. I could be an assistant at a major publishing house. I could even be a literary agent. I could be any of those things and a writer seeking representation, or I could be any of those things and writing an identical-looking business letter to discuss something entirely different from a novel query.

The whole purpose of the introductory paragraph in a document is to provide the reader with the same context the writer brings to the document. So it always feels redundant and overdone and silly because it’s stating out loud exactly what you’ve been thinking about since the moment you first realized you needed to write this document. The thing is, especially the way we do things today, your reader could be anybody. It goes so far beyond the literary agent having to guess if you’re a writer or an industry professional or somebody trying to sell him vinyl siding. The way we save data today, the reader could be the literary agent, or it could be his assistant, or his boss. It could be one of his students decades from now, when he’s given up representation and become a professor. It could be a graduate student decades later researching how I got my start in writing. It could be me decades later, looking back on where I got my start.

I still have every submission letter I’ve ever written. Most of them have lousy introductions, by the way. I still have most of the business letters I’ve ever written, for whatever reason. And I’ve got technical documents that I open up, scroll through a long list of technical information, and have to wonder why I pulled this information together, what purpose it served. For me, as much as for my audience, I need to write clear introductory paragraphs to establish a document’s context.

Some Technicalities
All of that took about fifteen minutes. I transitioned from that topic into a discussion of page headers, which we use more than anything to stamp the document’s title (and sometimes author) on the top of every page. It does for the page what the introductory paragraph does for the document — provides context. Footers mostly carry the page number, but sometimes other legal or contextual text gets stuffed down there, too.

I pulled up the class syllabus on the projector and showed them precisely that — every page had my name, the class name, and “Syllabus” in the header, and “Oklahoma Christian University” and a page number in the footer. By way of another example, I opened a copy of Gods Tomorrow and showed them how I used my name and the document title in the header, as any literary agent or submissions editor would require.

(We diverted into a little discussion of whether or not I’d give extra credit to them for reading my novel, when I caught some of them paying more attention to the text on the screen than to the headers and footers I was pointing out. I said no, because I already have plenty of phenomenal reviewers among you, my loyal readership. They were most disappointed.)

From there, I opened up a document template I’d built over the weekend, which consisted of two pages, landscape, with three columns per page. I walked them through the process of how to do each of those things in Word. Along the way I tried to show them how to insert Section breaks (so I could explain how Word handles different sections), and discovered that the lower resolution my monitor automatically switched to when I plugged in the overhead had truncated my menu bars, and as a result I couldn’t find the command to insert section breaks.

That severely interfered with some of the other stuff I wanted to show them, so I had to go on with the lecture describing how this document would behave hypothetically if I had inserted section breaks. Frustrating, but I didn’t let it get me flustered.

In-Class Activity
The whole formatting lecture only ran twenty minutes or so. When I was done, I said, “Now we’ve discussed some of the most frustrating things to work with in Word (columns and section breaks). I’ve got them all packed together onto this two-page template. Does anyone recognize this particular layout?” The only guess I got was a newspaper, but I didn’t wait too long. Instead I picked up a blank piece of paper, turned it sideways, and said, “What if those columns were filled with text, and I folded along the gaps between them?’

I did so, and immediately they recognized the shape of a tri-fold brochure. So then I told them they would get to experience the agony and frustration of working with columns and section breaks, because they were going to build a brochure.

First I had them divide into small groups (3-4 each), and everyone shared with the rest of the group what his or her semester project topic was. They’re each developing a new document with a real-world use, so I figured one out of every three or four would be worth promoting. So each group picked the project they thought would best fill a brochure, and got to work.

What I liked about that activity, more than the experience of making a brochure, was the way it got the students discussing their projects among themselves. They’re going to have to make a presentation to the class later in the semester, but this way they were able to practice discussing the project out loud in a much less formal environment. More than that, they were asking each other questions and expressing interest in each others’ projects in ways that I think will really help them move forward. And, of course, it helped that I got to eavesdrop on all of that from my place at the front of the room.

The Next Forty Minutes
I set them to work for the rest of the class period, and they took all of it. I’d intended to spend that time marking up the last of their proposals and then have them come to my desk one at a time to go over them, but I didn’t end up having enough time for that. In the end, I returned all but two of the proposals in the last few minutes of class, and those two I went home, marked up, and scanned in to return by email.

It wasn’t just time management that got me, though. I spent a lot of time interacting with the various groups, and they really got into the brochure project. I still remember trying to build my brochure from when I took the class under Gail Nash, and several of my classmates that I talked to about the class said that’s the only thing they remember from it.

Ten minutes into it, my class clown said to his groupmates, “To be honest, I’m not really a fan of the in-class activity.”

I looked up from the document I was marking up to hit him with a glare, and the English-major who’d joined his group went all wide-eyed and said, “Ohmygosh, he heard you!” Somehow, I didn’t laugh.

I shook my head and said, “Oh, he’s not scared of me. But, then, I haven’t picked his grade yet.”

That got a low chorus of, “Oooh,” but he immediately shrugged it off and said, “All I need in this class is a D. This is my last semester of my senior year, and I could get Ds in all my classes and still graduate, so there’s not a lot of pressure.”

Someone else jumped in to lament the fact that he was also in his last semester but he’d already hit his threshold of Ds, and from there the conversation turned to which classes had been cause Ds in the past — the primary candidates being “Western Civ” and “anything taught by Cami Agan.” That one made me smile.

Anwyay, in spite of his claim, he spent the full forty minutes putting together a great brochure, and I’ve seen no less effort on any of the papers he’s turned in. He admitted himself that he’s something of a perfectionist, so even if I don’t have a real threat to keep him in line, he’s still going to meet or exceed my expectations on all my documents.

In the end, I think his antics keep the rest of the students more engaged and casual, and ultimately I think that’s worth the little disruptions I have to deal with.

In the end, it was a pretty successful class period. I introduced Headers, Footers and Section Breaks in Microsoft Word (a topic that’ll also become a tutorial at some point later in the semester), and everybody practiced looking at their projects from a slightly different angle, which is going to be important moving forward.

More next week.