Skip to content

On Programming Language: Asterisks

Last fall I walked into my first ever teaching experience, with that junior-level Technical Writing course at Oklahoma Christian University that I’ve mentioned a time or two. I faced a room full of Computer Science and Information Systems students who were all within sight of their graduation, and faced with the first English class they’d had to take since their Freshman year.

That was intimidating. It can be difficult to turn Technical Writing into an interesting topic for even the most generous of audiences, and I had no reason to expect any of those guys to be generous. I was pretty confident before I ever met any of them that they all really resented me and my profession for even existing.

I had a secret weapon, though — an ace up my sleeve — and I brought it out in that very first class session. I dropped it casually into the conversation, but I made sure they knew from the very start that I was one of them.

I’m a programmer.

Halfway through the semester I finally backed that up, with a story about asterisks. See, at my work, we do frequent updates to existing documents, providing page changes instead of reprinting and reshipping dozens of thousand-page instruction books.

Now, the industry standard for page changes, to let readers know what on the page is new material (and so worth rereading), is to use black bars along the edge of the page. We don’t do that. We use asterisks in the margins — one in the left margin at the start of a change, and one in the right margin at the end of a change.

The problem with that method is that it’s not built-in. It’s something we have to do by hand, floating a text box over the page, typing an asterisk into it, and then dragging it into place. That’s a lot more work than just checking the “Show Change Bars” option in Microsoft Word and letting it take care of everything for us.

Worse yet, we’ve got some publishers further down the release cycle who are real sticklers for the appearance and placement of those floating text boxes. It’s not uncommon for a time-critical document to get approved by every subject matter expert and supervisor and manager in the process…and then get bounced back to us for correction because someone thinks the asterisk is a little bit too far to the left.

When I first learned about that situation, it seemed absolutely ridiculous to me, but I was told, “That’s just how things work here.” I wrinkled my nose, turned to Google to brush up on my Visual Basic for Applications, and then spent an afternoon writing a Word macro.

Now our branch has its own custom tool. When we’ve made a change on the page, all we have to do is highlight the changed paragraphs, and click a macro button on the toolbar. It automatically generates the two text boxes, styles the asterisks perfectly, and positions them within a hundredth of an inch exactly where they’re supposed to be.

The Advantage of Scripted Solutions

It’s a lot faster than putting in the text boxes was before, but much more importantly, it saves us lots of returns. We know that every time, with less effort, we’re getting it perfect.

I’ve talked about that before (and will again), but good automation can turn a hefty initial investment of time into huge rewards down the line — rewards in efficiency, in productivity, and — most important of all — in consistency.

Come back tomorrow, and I’ll tell you about the programming language that reads and writes so much like English that I couldn’t resist learning it, and the major advantages programming has provided to my writing.

Comments are closed.