File this one under “editor”, I suppose.
So I’m one week into the new gig, and today I finally got a chance to start wrangling with a first draft of an article on particle effects systems in a certain up-and-coming console game. If that doesn’t excite you, well, I don’t want to know you. Anyway, I was reading through it and realized a few things:
- Technical writers love awkward sentence structures.
- Awkward sentences make my eyes glaze over.
- Despite that, it still might actually be better for technical writing–especially on the Web. (Lucky me, I’m working in print.)
Let’s take a sample sentence:
Having many particle effects going on simultaneously can lead to problems with memory fragmentation.
Not bad. Perfectly readable. Personally, I don’t like the last half: can lead to problems with memory fragmentation. It’s not quite as economic or direct as it could be. I prefer:
Having many particle effects going on simultaneously can fragment your available memory.
That isn’t how I’d write it myself, necessarily, just how I’d tweak someone else’s writing. I find this more active and engaging while still fitting in the technical tone. However, it loses something in the change–that key phrase “memory fragmentation”. Which is important for two reasons:
- Google likes documents with keyword phrases like “memory fragmentation” more than “fragment your available memory”.
- Technically-minded folks tend to think of a sentence as a handful of keyword phrases connected by whatever connective tissue you need to communicate the relationship between those phrases, and maybe a verb in there somewhere.
Of course, the most important person in this equation is the reader, who in this case (as GDMag is an industry publication) has more technical chops than I do. I suspect that the average GDMag reader prefers a sentence which preserves the keyword phrases (which, as a technically-minded person, they’re also trained to seek out) in the most active manner possible–a balance, if you will, between friendly, engaging writing that is suited for a technical audience. But if I were writing for the Web, I’d want lots of keyword phrases (ideally in a really awkwardly-phrased headline). Well-written words that no one reads don’t get you much when that’s your job.
I also realized something different (but related) while editing this draft: Some technical folks seem to naturally think–and write–in passive voice.
We all know we’re not supposed to use passive voice. Sometimes we do it to obfuscate or downplay the agent of wrongdoing (ourselves). Sometimes we just do it because we think it sounds smarter. Sometimes that’s genuinely just how we think of the relationship of the words in the sentence–in part, no doubt, because our brains are learning to think in keyword phrases that we are then reluctant to break up. While I can’t think of many examples where I’ve preferred a passive sentence to an active one, I am starting to read more examples where it makes a weird sort of sense.
Like this particle systems draft, for example. The writer is describing a system that he and his fellow developers built. It’s a combination of art, code, and workflow that ends up producing the sparks from gunshots, steam from ventilation ducts, and explosions from cars. It seems too grandiose and self-centered to describe the system’s behavior solely as a product of the team’s work (we decided to build it like this, to do that). Better to speak in terms of what the system does–but since it’s not, strictly speaking, an agent itself, they simply describe the tasks that were performed. Memory fragmentation was resolved. Vertex buffers were cleared. Levels of detail were dynamically adjusted. And so on.
PM
Palette Swaps 