Monday, November 30, 2009

The OC (Weeks 12 and 13)

This post is part of an ongoing series.

Week 12
Back in August -- back when I had so much delicious free time on my hands that reactivating my WoW account seemed like a good idea -- I was just a bright-eyed kid all full of ideas. Those were the good old days, before bitter experience taught me the cynicism of reality. (In case you can't tell, I've been noveling.)

Anyway, back then I made up a course schedule to put in the syllabus, which included lecture topics for every week, and assignments for the students along the way. I mentioned the fallacy of that schedule in the week 11 post about technical writers as programmers, where I pretended a topic of actual interest to them was a topic I knew something about.

Week 12 featured a reversal of that, when I pretended a topic I knew something about was a topic of actual interest to them. The title for the lecture was "Writing to a Deadline and the Publication Process." I reversed the order for my presentation.

The Publication Process
By "the publication process" I meant the actual physical process that converts a Word file into a paper book. As a technical writer, that's a process that takes up a lot of my time. After I've finished writing a perfectly-crafted, error-free description of my topic, I then have to spend hours and days and weeks reshaping the beast to make it play nice with paper pages.

This reshaping takes two major forms: page design, and print options. Page design is stuff I can do in Word, like adding page breaks (and "Notes" pages, and "This page intentionally left blank." pages) to make sure new sections start on right-hand (front) pages, and adjusting space between paragraphs and illustration sizes to make nice full pages, and making sure every document's length (in pages) is a multiple of four.

I went to some effort to explain why that last bit matters. It has to do with printing on both sides of a double-wide sheet, and then folding it in half (producing a four-page fold called a "signature," which was a word I totally blanked on during the class). The reasons for this are complicated and partly apocryphal, but mostly they're just uninteresting. I won't bore you with the details.

Then there's print options, such as which print method you want to use. Offset printing (using big acid-etched copper plates and rolling rubber mats) is still far prettier than digital printing (using, y'know, lasers), but it's prohibitively expensive for small press runs (anything less than a hundred thousand copies), and it requires a lot of set-up time. As a technical writer, that's a really difficult balance to hit sometimes. As...anyone else, it doesn't matter. Offset printing is just outside the price range of the housewife putting together a cookbook, and printing contracts at most companies are handled by accounting or documentation departments, not the programmers and engineers who are taking my class.

Still, it's the technical process by which we make real things out of the documents they're building in Word, and I felt like I should go over it.

I also discussed the various binding methods -- from three-ring binders and spiral-bindings to the hardback ("case" binding) and paperback ("perfect" binding) you'll find on the shelves at B&N. I discussed the benefits and drawbacks of each, showed some samples, and then moved on.

Writing to a Deadline
Writing to a deadline is the biggest challenge of the technical writer (whether it's a job title or just a job requirement). The nature of the deadline varies from shop to shop, and I demonstrated that by talking about my personal experience again. At Lowrance, we typically received an assignment with three days to build a hundred-plus-page book. Sometimes we had to turn it overnight. At the FAA...the Maintenance Handbook project I just finished was one of my top priorities for most of the last year. Once it was officially given to me, the deadline was a vague "soon" for months before it became, all of a sudden, "Friday."

There's a commonality in both cases, though. In all technical writing, really, the information you're supposed to be putting into a document comes to you at a trickle -- an agonizingly slow trickle at times. At Lowrance, we knew what products were in the works for months, but it would be three days before packaging before we had a working model to test and grab screenshots on.

Your job as a technical writer is to get as much information on paper as you can, as early as you can, without wasting too much time. That last bit can be the tricky bit, because we could easily have built a bunch of documents at Lowrance using early emulators, and then had to scrap 90% of our work because of a single software change (and we often did).

The other difficulty you'll encounter when you're writing to a deadline, I told them, is that you'll get called into meetings, or have to attend training, or deal with any manner of pompous windbags who monopolize your time to tell you about something incredibly important to them, but that has no relevance to your project (or your life) whatsoever.

The best thing to do in those cases, I've found, is to have your laptop open on the table in front of you and just spend the whole lecture working on your project. (That got a laugh.)

Work Time
That whole lecture took forty minutes or so (as intended), and I left them the rest of the time to work on their projects and ask questions. They did, and some even hung around after the end of the period, so it was 2:30 before I headed home.

I sent out an email later that week to let them know the following Tuesday would be exclusively work time. I promised to be available (in class) if they had any questions or needed advice, but that I wouldn't have a lecture prepared, and I wouldn't be taking attendance. I also sent an email to several of the other professors inviting them to stop by and keep me company, because I didn't expect any of my students to actually show up.

Week 13
Some of them did. Three, actually, which doesn't sound very impressive, but it amounts to 20% of my class, so it's not too shabby. I barely broke 50% on Week 12, and I did take attendance that week. (That was my only low week, though, and they did know it was going to be partly a work period.)

Anyway, I had some great questions from the students who showed up, and I'm pretty confident they're going to have great projects to turn in. I also got to chat with one of my students about Google Wave for half an hour, which was both fun and educational.

Oh, and I got all my dailies done. So it was a productive period all around.

All I've got left now is presentations, evaluations, and the final exam. Oh, and the grading. I tremble at the thought of all the grading to be done. Still, the semester is mostly survived, and I think I've done some real good. Yay me.

More next week.

Monday, November 16, 2009

National Novel Writing Month 2009 Progress Report

I'm fifteen days into NaNoWriMo, and doing terribly well.

Well, okay, sixteen days. I was going for the parallelism, though, so shut up!

I made a long post to my writing group's discussion board last week talking about goals -- specific, personal goals, and the impetus to reach them. The gist of it was that I had one: I wanted to finish Ghost Targets: Restraint (which I began back in June) by the 16th, when Julie and Carlos were coming by for a visit.

I did that. I actually finished the story last Friday afternoon, which put me at 29,000 words in November, and 55,000 words in the book. For those of you who are good at math (and know the rules of NaNoWriMo), you'll be wondering what I plan to do with my other 21,000 words in the next two weeks.

As of now, I'm undecided. In the last three days, I've written a couple pages of introduction for a totally new story idea (that's intended to be a collaborative project with Courtney), a couple pages of introduction for the next Ghost Targets book (which is currently laboring under the working title Shelter), and today, over lunch, four more pages that drive me a good distance into chapter one.

I'd spent the early part of the month thinking I was going to finish up my Sleeping Kings opener, Golden Age, and I'd still really like to do that. It's complicated, though. I was a different kind of writer when I wrote the SK books, and I don't think it would be worth the effort to rewrite the whole series to bring it more in line with my current writing style, but I don't know how well I can fake the old style to get a seamless introduction.

And, at the end of the day, I've got a lot more energy behind the Ghost Targets series now. I could end the month with a third of the fourth book done and soar past 50,000 for the month, and all of that would be pretty effortless. Or I could labor over every page, force out a passable introduction to Sleeping Kings, and barely hit my target even with all the extra effort. It would be awfully nice to have that done, but I don't know that I have the discipline or the motivation to make it happen.

Either way, I'm limping into my pre-class downtime today, so it'll be sometime Thursday before we know more. Well, before I know more. Chances are good this space won't be updated until the end of the month, though, and by then it'll be done, one way or another.

If you've got an opinion, feel free to cast your vote. Maybe you'll surprise me. Maybe you'll even motivate me.

Other than that, it's just things and stuff.

Thursday, November 12, 2009

The OC (Week 11)

This post is part of an ongoing series.

Scary Professor Guy
I brought back Scary Professor Guy to open the class this week when, two or three minutes into our class period, one of my Juniors was still trying to get one of my Seniors to help her with her programming homework.

I barked, "Okay, okay, go sit down. We're not here to talk about programming, we're here to talk about technical writing." She blushed a little and went back to her seat, I had all eyes on me, and said, "Right. Today's class topic is 'Programming as a Technical Writer.'" That got a laugh.

Talking Points
Before we got to the lecture, though, I had them go around the room and everyone described his or her semester project. Briefly. I had a couple goals in mind with this, but the main one was just to force them to think about their semester projects. They did that three weeks ago when they wrote up their proposal, and probably not a moment since then. So I sent out an email last weekend letting them know they'd be responsible for talking about their projects during class on Tuesday.

Their assignment today (due next Tuesday) is a progress report, but I was hoping the threat of public speaking would drive them to get started a little sooner, so they'd actually have some progress to report.

I imagined it could take as much as half an hour to go around the room (leaving me forty-five minutes for my lecture) but I went ahead and prepared an hour's worth of material just in case. In reality, it took fifty minutes to go around the room, so I not only cut the disposable fifteen minutes, I had to do some major compression on my core lesson.

The presentations were useful, though. I'm sure the students were bored of it about halfway through, but most of them were encountering (or will encounter) similar problems and frustrations. Most of those problems are inherent aspects of technical writing, so it's not like I could give them advice to get around them, but at least they'll know they're not alone.

Programming as a Technical Writer
I'd sort of looked forward to this lecture ever since I found out just how many programmers I had in my class -- my opportunity to show them how useful programming can be in tech writing and (just in passing) how incredibly cool I am, as I've done all these things.

The better I got to know them, though, the more I realized that the stuff I had to tell them didn't merit a class (or two -- I'd originally scheduled another lecture on "HTML, XML, and Structured Documentation," in addition to this one). I've got three English majors who could all really benefit from a course in each of those topics, but I wasn't going to be able to teach them Python in seventy-five minutes, and I couldn't justify making all my programmers sit quietly while I tried.

So, instead, I adjust my focus. Instead of trying to teach when and how to use which tools, I converted my case studies into object lessons. That may seem like a pretty narrow distinction, but it's a matter of scale. I only had twenty minutes, anyway, so I briefly described several of my big projects (in terms of efficiency improvement), and then I leaned heavy on the take-away lesson.

The take-away lesson is this: automating tasks can be difficult to set up, but it makes those tasks easier every time you have to perform them afterward. Your job is to determine (and it's a matter of constant re-evaluation) if the set-up expense is worth the efficiency reward.

If you're a programmer, that expense is often just the amount of time it takes to make and refine your program. I have half a dozen examples ready to hand where I was able to save hours and hours off of every document we produced with just a couple hours of research and coding. If you're not a technical person, though, that expense can require weeks or months learning a new skillset, or days refreshing your understanding of one you haven't used in a while. Still, there are some projects large enough that a semester of training is worthwhile to write a script to process the thousands of pages of data you'll be dealing with.

I didn't try to teach them how to do anything specific. I would have, if the projector had worked like it's supposed to. I would have probably kept them late so I could show them how to put together a quick VBA macro in Word, but now I'll just save that for a Thursday tutorial later in the month. As it was, I just told them about a couple times in my experience where quick Python scripts or clumsy VBA macros made my life much, much easier.

Progress Report
Their assignment today, as I mentioned, is to write a progress report on their Semester Projects. I had them create Google Docs account last week, so I decided to make this week's assignment be a new Google Doc. In their tutorial I showed them how to set up and format a Google Doc from scratch, and then how to load and modify a Google Docs template to achieve a similar (but prettier) effect. Now they're supposed to fill in one of those two documents with the information required by their assignment, and then share it out to me.

I'm anxious to see how that goes. I'll let you know.

More next week.

Wednesday, November 11, 2009

Vanity Plate

I talked about it a lot back when it happened, but I don't think I ever posted any of the photos Julie took when she came up to do the maternity shoot for Trish.

I asked her to get a couple of me for profile pics, and this is the one I'm using now.


Thanks again to Julie for her great work. She's said she wants to take another run at it, and that sounds like a blast. Until then, though, I'm perfectly happy with the work she did.

Monday, November 9, 2009

The OC (Week 10)

This post is part of an ongoing series.

Pulling My Punchlines
Last week's class was disappointing. I think, of all the classes I've prepared this semester, the only one I was more excited about (beforehand) was the one with the band flyers. That time I was excited about the in-class activity, though. This time I was excited about the lecture.

Because I had good material. Dad told me before Week 2 that I had to focus on how I could make their lives better, and this class was all about that. I had so much good information to impart, I just knew it would be a great class.

And it was not, by any means, a bad class. The information was good, the students paid attention, I filled an hour but didn't keep them late. It was a good class, but it lacked punch. None of my excitement really got through, because (for the first time) I felt comfortable enough before class that I didn't invest much preparation in the presentation. Turns out, I'm still not a natural. I didn't have any punchlines, so I'd spend ten minutes telling them how cool this feature was, or how that program worked, but I failed to drive home how it would impact them. I guess a good activity could have served that purpose, but I had so much I wanted to cover that I didn't really have time for one.

Or...well, I did. It just wasn't in-class. I'll talk about that more later.

Markup
The class covered "Collaborative Writing and Editing Tools," and the most basic of those is markup. Markup, as I told them, is the process of providing feedback on a documentation product using a consistent, somewhat standard set of marks and symbols. You're probably familiar with the paragraph mark, which can be penned into the middle of a long paragraph to recommend a good spot to break it up. You might be familiar with the strikethrough line ending in a little swirl to indicate text that should be removed. If you don't do a lot of markup, you're more likely to just cross out text you think should go.

There are a bunch of standard marks, but there's also a bunch of standards, so it's hard to find one reliable set. Because of that, I stressed "consistent" more heavily than "standard," and showed them (very quickly) how to look up a set of editing marks online.

Before I got to that, I had a little slideshow ready, and I flashed hand-drawn samples of my personal markup on the screen, and asked them to identify the meaning. They've been getting markup from me all semester, so they had no trouble with that process.

The problem with markup is that it's slow. A document's author has to create a baseline document, get it to an editor, wait for the editor to suggest changes, and then incorporate those changes into his baseline. If the author tries to continue working while that's going on, he risks invalidating much of the feedback he'll get from the editor. If he wants several different people to review his document (without a lot of wasted effort) he has to go through the whole process separately (in order) with each editor.

Track Changes
Word makes things a little easier by allowing direct modification within documents. Instead of printing out a copy for my boss to mark up, I can email her a copy of a document I'm working on and she can make any recommended changes directly. To preserve author control, she can activate a tool called "Track Changes," which allows Word to keep track of every modification she makes to the document.

When I get that document back from her, I can change some view settings to see what the original looked like (my document), what the final looks like (her suggested version), or "Final with Markup." Turning on that last option shows me a visual record of every change she made, and I can right-click any one of those and choose "Accept Change" or "Reject Change." Once I do that, the markup goes away, and I'm left with the text I want, as the document's author.

That only eliminates one step in the markup process, but it speeds things up a lot, and it allows the editor to make much more detailed suggestions (in the form of actual changes). Word also offers a Comment which allows an editor to attach a note to a document he's reviewing without actually modifying the text any. Something like "Should we say more here?" maybe, or "Check this figure number."

The nice thing about all of this is that I can keep all of the markup available when I need it, but just change my viewing option to "Final" when I need to see (or print) a clean document.

Collaborative Writing
Still (you all knew this was coming), markup is just a clumsy process given the tools we have available now. After talking through the ways we can do markup, and get the most out of it, I opened up my Google Docs folder on the screen and started really preaching.

With tools like Google Docs, it's easy for multiple authors to work on a single document. By way of example, I opened some of the (many) documents in my folder. I showed them my Class Topics document, which I keep on Google Docs so I can update it from anywhere, whenever I have a moment and an idea. I showed them a spreadsheet I use to track some stuff I'm working on in WoW, just as a sort of virtual Post-It Note (to stress the simplicity of creating and maintaining documents). I showed them our NaNoWriMo spreadsheet, as an example of one that has a lot of editors viewing and modifying all the time.

When that one went up, I launched into my little speech. "This makes it easy for any of us to open it up at any time and update our word count--"

And someone said, "Yeah, and you can see just how bad you're doing." At that point I had about 1,100 words, which put me dead last among the people on that list, and around 1/5 of my target, so I didn't disagree.

Someone else said, "Wow, Courtney's really smoking!" She was a hair shy of 6,000 words.

So I came out from behind my podium, shaking a finger at them, and said, "Oh, yeah, sure. But she's a full time novelist. That's what she does. And me? I've got a day job. I've got two kids. Oh, and I've got to teach you guys." I put some venom in that, and they all laughed.

Real-time Feedback
Then I opened a couple more documents, copies of Gods Tomorrow that I'd shared with Carlos and Courtney, and showed them how they'd provided feedback right in the document -- Courtney with color-coded comments between paragraphs, and Carlos with footnotes, that behave just like the Comments in Word.

That's really my favorite use of Google Docs, because it lets me watch a reader reading my books. That has got to be the greatest thrill for a writer.

Change History
Of course, giving them the ability to change my documents creates a little bit of a security concern. Both of those documents were copies of my original, but to get the most out of collaborative writing, you're eventually going to have to relinquish some control, and that creates the possibility for a reckless editor to really mess up a document.

Google Docs (and, really, any modern collaborative writing software) handles that by tracking changes. I can open any of my Google Docs and view a list of every change that has ever been made to it, all the way back to the original blank page. Not only that, but I can see who made each change, I can compare versions, I can revert to an old copy. It's incredibly powerful.

So I talked through that process, and (really like everything I'd shown them in Google Docs) it was mostly showing how Google had implemented useful collaboration tools available elsewhere, because I'd started the class talking about version control software, and how to make the most of it. The real key is to keep on top of the changes being made to a document you're responsible for -- know who's working on it, what they're doing to it, and be sure to catch any serious problems early. As long as you're paying attention, it's easy enough to protect the quality of your document in a system like that.

The Punchline
To close the class, I opened a final document on the screen -- the instruction sheet from an AirSoft gun (which is to say, really terribly translated English with some cheap illustrations). You can see the original here, if you're curious. For the Google Doc, I just copied all the text over verbatim, and put it in a plain text document.

Then I told them that their assignment for the week was to fix that document. On Thursday, when they got their tutorial, I walked them through the process of setting up a Google Docs account, and then required them to send me a copy of the email they'd used. Once I had that, I invited each of them to collaborate on that document. I also set up a spreadsheet to use for presentation sign-up, instead of passing around a sheet of paper at the next class.

That, I think, will do more to sell them on the usefulness of this information than anything I did in class on Tuesday. They'll be able to see collaborative editing in action, they'll see their classmates modifying a document they have open in real-time, and at the end of the day they'll have a Google Docs account set up. It's another weapon in their arsenal. They're better able to handle real-world writing challenges this week than they were last week, and that's really all I was ever going for.

More next week.

Thursday, November 5, 2009

National Novel Writing Month 2009 Kick-Off

I'm five days into NaNoWriMo, and not doing terribly well. I'm right at 1/4 of my target word count. My writing group is on fire, though, and I'm taking a little bit of (probably undeserved) paternal pride in that.

We started things off in a big way last Saturday night (Halloween), when a bunch of us met at a local IHOP for a big kick-off party. I think I've seen differing counts, but I'm pretty sure there were seven of us writing (and an eighth writer who left before we actually started writing), and two visitors who came by just to spectate.

We met at 11:00 PM, so that we could socialize a bit before getting down to business. I spent most of that time talking with Shawn about World of Warcraft. That was, without question, an accurate indicator of what I should expect out of the night, and out of my November. Don't mistake that for me placing blame anywhere but on me, though.

Anyway, it was fun, and we all had a good time socializing. There was a real air of anticipation, too, as we got closer and closer to midnight. Somewhere in the midst of that, a young couple headed toward our tables -- one of the seven writers, and one of the two spectators. The latter of those was also one of my students in my Tech Writing class. He's a young man with considerable personality -- more than he can reasonably keep to himself.

It was my intention to get 2,500 words written. I was willing to leave as early as 1:00 if I managed to hit my word count by then, but I was expecting it to take until about 2:00. That's okay -- I've closed down bars in the not-too-distant past, so I figured I could handle 2:00. We had the advantage of Sunday morning being the end of Daylight Savings Time, too, so I'd get the extra hour of sleep.

Most of our writers had laptops -- no, check that, all of them did. Except me. I had a scribblebook, because that's how I roll. We'd picked IHOP for its late hours, but one of the major selling points had been the free WIFI. Unfortunately, when midnight rolled around and everyone opened up the laptops, we found ourselves unable to locate that free WIFI. I don't think anybody ever did. There wasn't easy access to electrical outlets, either, but I think everyone's batteries survived longer than their writing impetus, anyway.

Anyway. While they were wrestling with their network management utilities, I was scribbling in a cramped cursive at laughing at them all. Muah hahaha! I filled two and half pages (a hair over 500 words), and ran out of words. I spent the next thirty minutes or so forcing words one at a time to fill another page and a half, and then I gave up. Oh, what a shining example I am for my writing group!

About five minutes before I gave up, though, my oh-so-personable student Sean (no, not Shawn, that was someone else) gave up on his project to get ad hoc StarCraft going, and came to our tables to talk some more. I was able to pretend to humor him, and act all friendly as an excuse for closing my scribblebook, unclicking my Pilot G-2, and spending the rest of the night just emptying glass after glass of Coke.

That was one-ish, so I had an hour left before I was going to let myself leave. Fifteen to two, a hostess came by our table to warn us that the bars were about to let out, and the clientele would become considerably more boorish. Courtney proudly proclaimed that we were writers, and we delighted in observing vibrant characters in action.

We got more than we bargained for there, though. Just past two, a fistfight erupted in the parking lot which quickly ended up as four guys beating the hell out of a fifth guy down on the ground. Our table gave us an easy view of it, but everyone in the restaurant was quickly on their feet, watching the fight through the wall of windows. It was impossible to look away.

Courtney called the cops. A manager and some employees risked their lives to try to intervene (and quite possibly saved the fifth dude's life in the process). Fifteen minutes passed before the ambulance and firetruck showed up, forty-five before the cops. None of us really felt like setting foot outside until that happened.

So I stumbled in the door well after three in the morning, too buzzed on secondhand adrenaline and caffeine to fall asleep, and I spent half an hour lying in bed thinking, "Oh, the hangover tomorrow is going to suck." That was habit, because the only time I come home after two in the morning is when I've been out drinking (and, when I spend that long out drinking, the hangover tomorrow always sucks). I kept having to remind myself I hadn't actually had anything to drink.

And then tomorrow came, and the hangover was awful. I'm way too old for three in the morning.

I cleared eleven hundred words on day one, and then had to go to work on day two. I taught a class on day three. I've been swamped with a Maintenance Handbook on a Nov. 14th deadline, and too exhausted at the end of the day to do anything but log in and zone out. I ended yesterday at 2,485 words. Got another five hundred done today, though, and the weekend is looking shiny and full of promise.

Every novel I've ever written has had at least one 8,000-word day in it. Maybe this year's will come early.

Anyway, that's most of what's been on my mind. I'm off to a slow start, but I'm still a long way from out of the game.

Other than that, it's just things and stuff.