Blog: Writing

Most of these posts were originally posted somewhere else and link to the originals. While this blog is not set up for comments, the original locations generally are, and I welcome comments there. Sorry for the inconvenience.

At the end of the day

A short story in three acts.

Image without description

Matt sat in the back row of his freshman anthropology class, browsing Twitter on his phone. Kevin, sitting next to him, whispered, “careful, he’s looking this way.”

Professor Ramirez paused, then nodded toward the student sitting two rows in front of them. “Yes, Leonard?”

“Are you saying these primitive people actually believed that the sun was being swallowed by a dragon? I mean, haven’t we known about eclipses for thousands of years? It’s not rocket science.”

“Be careful what you dismiss,” the professor responded. “There are people alive even today in remote places who don’t have the benefits of science that we take for granted.” His eyes fell on Matt and Kevin. “Science isn’t just for surfing the Internet during class. It also…” Matt looked up, blushing, but the professor had moved on. Matt tapped a few times on his phone.

“Ah bummer,” he whispered to Kevin. “We don’t get a total eclipse here for another seven years. I wish we were seeing today’s show instead of sitting here.”

The shaman’s frenzied dance did nothing to deter the darkness overhead. Frightened villagers gathered around. Infants wailed, drowning out the erratic sounds of confused wildlife.

The village elder pushed his way through the crowd and stood in front of the shaman. The shaman stilled his skyward exhortations. The elder met his gaze. “Why?”

The shaman shook in fright. “I do not know, master. We have been diligent in making our offerings to the gods. We fed the dragon just last full-moon!”

The elder’s gaze fell on a man, now childless. Tears streamed down the man’s face. Had his daughter’s sacrifice been for nothing?

The sky continued to darken. A rock flew through the crowd, smashing into the father of the most recent offering. Someone shouted “unfit! what have you done to us?” Others shouted back. Fists met faces, and some reached for clubs. The village elder’s cries for order went unheard in the eruption surrounding him. The glow of just-lit torches spread through the crowd. The shaman stood still, gazing up with pleading eyes.

Darkness covered the land. The light did not return.

“I see you’ve finally tired of playing with your food.”

N’zok belched and moved closer to his mate, placing his vast left wing over her back in a partial embrace. “This system was getting boring. Thank you for indulging me.”

“Where to next?”

N’zok rotated in space, turning his mate with him. With a claw he gestured toward a bright light. “You can’t see it from here, but there are two stars in that system, one for each of us. We should be happy there for a long time.”

“Is there any chance you’ll consider eating slowly this time instead of wolfing it down? That’s so barbaric.”

N’zok belched again. “Barbaric, but oh so tasty!”

Both dragons unfurled their wings — unnecessary in the vacuum of space, but N’zok appreciated the aesthetics. They began their slow movement toward the binary star.

Questions for the interviewer (tech writing)

Somebody on a tech-writing mailing list just asked what kinds of questions we tend to ask interviewers when we're interviewing for jobs. The person had already mentioned, specifically for hardware-related jobs:

  • Do you test the documentation? How?
  • How does legal review work (for things like liability)?
  • Availability of subject-matter experts for reviews?

Here's what I wrote in response:

My experience is in software, which might be different from hardware, but I always want to know:

  • How early and in what way are writers involved in development? Do writers participate in functional and design reviews? Do we have input into the user interface? Are we part of the team, or do we come in later, take what they've built, and document it?

  • Can I use the product? As much as I want?

  • What processes do both the dev and doc teams follow? (If they say "agile" there are more questions.) How is doc reviewed and by whom?

  • (How) do we make doc improvements that aren't directly tied to new features or bugs? (For example: larger reorganizations, improving indexing, adding runnable examples, tools improvements.)

  • (How) do you use source control for documentation?

That's off the top of my head, without digging out my notes from my last round of interviews.

So that's not a complete list either, but these are the kinds of things I tend to be thinking about. (I also try to find out if I have access to the source code, but since he was asking about hardware I didn't bring that up.)

I also want to know where the documentation group is placed, organizationally speaking, but I usually learn that indirectly.

In the comments, somebody wrote:

I don't think I've ever been involved in an Agile process that included Doc in the core team, but now that you raise the point, that's clearly a process failure.

I responded:

After my first (full, not intern) position where I was included as part of the core team, I've made it a hard requirement. Fortunately, since then, I've been able to insist -- meaning that (a) so far I can afford to be picky and (b) I have a very solid track record that means I don't get dismissed out of hand. People just starting out won't necessarily have those traits, but I always advise people to, at the very least, prefer companies where they'll be part of the core team if they're comparing offers.

The cost, to the doc person, of being included early is that you might have to redo some work and/or relearn some things, because until the feature is finished it can still change even though everybody agreed on a design. That happens -- QA discovers a performance problem that can be alleviated if you make this small change to the interface contract, or it turns out that this is inconsistent in some way that matters with that feature over there that's also going into this release, or whatever. (But I don't need to lecture you about this; you know how software-dev works.) So that's the cost, but against that there are huge benefits for the team. You alluded to UX benefits; specifically, doc people are already looking at things from the user perspective so they'll spot things or have suggestions that people deep in the implementation might not think of. In most organization, in my experience, there are a lot fewer writers than developers and a writer might be working with more than one dev team -- and therefore might know some of what's going on in that team over there that affects this one here. And a really big one IMO: trying to explain something is a really good way to find problems in it. You know this from rubber-ducking. So even if some work might have to be revised, I want a writer to be trying to explain the new thing early, early enough to make changes when those problems emerge. (A writer, in turn, learns to use a breadth-first approach and focus on key areas for early deep dives. If you're working like this you don't start at the beginning of the doc and work your way through it in order.)

Of course, I've too-rarely worked anywhere that had genuine professionals doing the documentation to begin with, which says something in and of itself.

That's true lots of places, yeah. And, to be fair, there are more than a few technical writers out there who don't know how to work in this kind of environment, who struggle with changing requirements, or who just want to start with a finished thing so they can take an orderly approach to the doc instead of helping to make the thing. It'd drive me nuts, but not everybody is like me. There's also a lot of poor "walk the menus" (or equivalent) documentation out there that makes people think that's all technical writers can do, and that doesn't help. I've had several senior developers and dev managers say to me, after some time working together, variations on "I had no idea that tech writers could do what you do" -- they'd never seen it before. I'm not saying this to brag; this is as much about mindset as it is about raw skills, after all. But it's something I've tried to imbue in every junior writer I've mentored over the years.

Psychological effects of teleportation

Somebody asked about the psychological effects of instantaneous teleportation like in Star Trek. If your location changed drastically and instantaneously, would you experience cognitive dissonance? How might one mitigate negative effects?

I answered: Read more…

Worldbuilding as you go: a case study

Posted on the blog for the Worldbuilding community on Stack Exchange.

In the board game Eurorails, players build and use a railroad network. In the beginning you don’t have much money to pay for track, and the way you get money is to use your track to deliver goods from place to place. As a result, you end up building your track as you go, balancing short-term needs (I need to go to Berlin) and long-term needs (I need to cross the Alps eventually). Some of your needs might evolve and change over the course of the game, requiring you to adapt your building plans. (I just got a high-value order for oranges to Oslo and I can just barely build that line to Barcelona to get them…) Until the end of the game, your track is constantly under development.

I’ve found that playing Eurorails has a lot in common with building worlds for fiction or role-playing games.

Eurorails board, from Board Game Geek, used with permission

There are lots of approaches to worldbuilding. All of them are right for somebody. This article isn’t about telling you what to do. It’s about showing you what works for me, in hopes that it might work for you too.

I’m going to illustrate using the world for The Sisters’ War, the story I’ve been writing for this blog. (You don’t need to have read the story to follow this article.) Read more…

The things you learn...

Somebody asked a question on Stack Exchange about batch-converting document reference numbers (like ISBNs but for papers, not just books) to full citations, which sounded like a "simple matter of programming web services", so I did a little poking around. I have a (single) peer-reviewed publication, so I looked up its reference number (DOI) to test with.

That's how I found out that I have two publications. Er, what? Apparently that paper ended up in a book several years later, and apparently the process of doing that calls for neither permission from nor notification to authors. Or at least second-string authors; maybe the lead author was involved. (I wouldn't know; I haven't interacted with him in ages.) It's a paper in computational linguistics; I was just the (main) programmer, not the linguist or the PhD.

Building worlds for fiction vs. role-playing games: what's different?

Somebody asked, on a worldbuilding community: what's different, for the worldbuilder, in building a world for a story versus building one for a role-playing game? I answered:

The differences are fairly subtle. In both cases you need a world that's well-enough developed to be plausible and interesting to the people consuming it (readers or players). But there's an important difference: RPGs have players.

Well duh, you're probably saying. Let me unpack that. Read more…


A writing site I'm part of has a weekly writing challenge -- somebody throws out a topic, you write for ten minutes, and then share what you've got. I decided to try it this week. The topic was "high school crush".

He opened his eyes to the cacophony of voices. Faces came into focus -- Mr. Jacobson, a man in uniform -- wait, police? -- and a giant towering over him. Was that the truck driver? He tried to clear the fog from his brain as he reached up and brushed broken glass from his hair.

"Don't try to move; you're hurt", someone behind him said. Another face came into view, a man wearing glasses in which flashing red lights were reflected. "We'll get you out of there, hold on", the stranger said.

Hands pulled him free of a jumble of metal and glass, pulled him onto a stretcher. "No wait, I'm ok", he said as he tried to stand, wobbled, and fell back. He noticed for the first time the shooting pain.

He returned that afternoon, swaying on crutches into his chemistry class. Darn, he said, couldn't they have taken another 45 minutes at the ER? He hated this class, his last of the day.

Just before the bell the speakers crackled, calling the class to attention. "Driver ed is cancelled tomorrow due to mechanical issues", the voice said. Mechanical issues, eh? No, no amount of body work was going to fix that crushed mess; they were going to need a new car.

What, you were expecting romance?

"7 things" #3

There was a parlor game going around where someone else picks seven things for you to write about and you do -- short or long, meaningful or random.

Alaric gave me: Pittsburgh, writing, your favorite song, chicken, D&D, knowledge, and al-Andalus. Read more…

How LISP changed my professional life

Part of that "seven things" meme:


The most valuable part of my education as a technical writer was my student internship with the Common LISP project. It was also either the first- or second-most important part of my education as a software developer. Yes yes, the classroom stuff was important and the software-engineering project course was essential for putting the pieces together, but this was the real world and the real world is far less tidy than the classroom.

I was brought on to help write the documentation for this then-in-development language. (Other varieties of LISP existed; this was an attempt to unify them.) But unlike all my previous tech-writing work, this was for a thing that did not fully exist yet, and I was part of the ongoing design process. I was there in the (virtual) room with the lead designers, Guy Steele, Dave Moon and dozens of others big and small, and if my contributions had merit it didn't matter that I was an undergraduate with no real experience. On the ARPAnet nobody knows you're a dog undergrad. Mind, being an undergraduate with no real experience, I didn't necessarily have a lot of design ideas to contribute, but even then I was pretty good at catching inconsistencies and asking key questions. I learned to write software-interface documentation there, but even more importantly I learned to be part of a real software-development process, to ask questions even if they might seem "stupid", to argue for technical positions and support those arguments, and to be a full member of a team.

When I graduated and met more of the real world I would learn that it usually doesn't work like this. In a lot of places, tech writers are not part of the development process (and may not even be in the development department) and the attitude is that they can come in after the big boys are done developing the product. Phooey on that; this important early experience taught me that it doesn't have to be that way, and I have held firm on this in every place I've ever worked. If I hadn't had this early lesson, I might well have fled the field.

It is also because of the Common LISP project that I went into programmer documentation (and expanded from there). I wouldn't have pursued tech-writing jobs that were all about walking the menus in the UI and stepping through wizards and such; I want to look under the hood, understand what's there, and use that knowledge to help users. Building software development kits like I do now is exciting and nourishes my inner geek. When I went to college I hadn't even heard of technical writing (I went there to do computer science), but I came out as a technically-proficient writer who knows the good that is possible. I have Common LISP to thank for that.

Never seen that in a job posting before...

From a job posting for an API Technical Writer (sic):

"Our ideal candidate [...] Comfortable authoring in HTML and XML using plain-text editors (no WYSIWYG)"

That's how I work all the time. I didn't know anybody else cared. :-)

(Because (1) after 30+ years the emacs muscle-memory is strong; (2) it means I actually know the spec (at least the important parts); (3) I don't have to clean up after tools' bad decisions about what I meant.)