Skip to content

On Programming Language: The Advantage of Scripted Solutions

Writers are not naturally programmers. I’m certainly aware of that. In fact, I resisted becoming one for years even though all my friends were.

When I finally broke down and accepted some lessons from my friend Toby, though, it changed the way I approach everything I do on the computer. Some tasks require a lot of thought, and a little bit of execution. Other tasks require a little bit of thought, and a ton of repetition.

That goes for video games, file management, internet research, and everything else a person does on the computer. And it goes double for Technical Writing.

Management and Repetition

While Creative Writing is all about the way you say things, there’s not a lot of that in Technical Writing. The actual prose in Tech Writing is usually extremely straightforward and…well, technical.

There’s a huge demand for clarity there, though, and that means a Tech Writer spends a lot less time writing a page, and a lot more time organizing it. Specifically, there’s a lot of text management (controlling things like position and style) and repetitive writing (writing text that matches the template’s required sections as closely as possible).

The good news is that those things lend themselves well to automation. It’s the fundamental principle behind using templates and styles in the first place, and once you know a little bit about programming, you can write scripts that manipulate the text within your template and styles to update a whole document at once (instead of repeating the same set of changes again and again through every paragraph in a document.

Just as a quick example, I spent last week cleaning up a draft document I’d received from an engineer. The guy who wrote it is a technical genius, but he’s not terribly familiar with Microsoft Word, so when it came time to prepare his pages, he did what he could to make them look the way he knew they were supposed to.

A Warning, for instance, is supposed to be centered on the page, with margins inset an extra half an inch on both sides. He did that by adding a paragraph break at the end of every line (hitting Enter), and then holding down the space bar to try to position the left margin of each following line approximately where it needed to be.

The result was a mess, and when I wanted to apply styles to the paragraph (which he’d broken into a dozen paragraphs), I had to fix it. Looking further in the document, I found that he’d done that for every warning in the whole book.

So I wrote a macro that allowed me to select the whole block of text, remove all but the last paragraph break, and replace any big block of spaces to just one space. It took me ten minutes to write the macro, and then all I had to do each time I found a warning was select the whole thing, and run my script.

That still left me the task of translating his engineer-speak into good clear English, but that’s the fun! And that’s the point. Automating the easy stuff frees you up to spend more time on the challenging stuff (which is almost always more fun, anyway).

Keeping It Consistent

There’s another big advantage to learning to work with automation, and it’s one I’ve mentioned before.The whole process of automation, though, involves finding a set of consistent rules (such as, for instance, “remove all but the last paragraph break in a selection and reduce blocks of multiple spaces to a single space”), and then figuring out how to apply them.

The beautiful thing about working that way is that a script won’t cut corners or make little tweaks here and there to get the prettiest results — it will follow the exact rules you get it, in the same way and in the same order every time. That gives you an amazing consistency in your document’s design, and consistency is the  gold standard of Technical Writing.

Diving Into Python

I’ve mentioned a couple examples of scripts I wrote to manipulate Word documents, both yesterday and today, and those have all been in Visual Basic for Applications (VBA). That’s a programming language built into Word, but it’s a real pain.

Oh, don’t get me wrong! It’s worth learning, for all the reasons I’ve shared in those same examples, but it’s not a great place to start. You’d be much better suited learning a real, robust scripting language, and the one I recommend just happens to very English-like.

So come back tomorrow to learn about the Python programming language, and make your writing process far more powerful.

Comments are closed.