Perspectives on technical writing

Technically We Write is an open community about technical communication. One of our first community members is Seth Kenlon, who recently contributed articles about 5 things you didn't know about styles in your word processor and Tables and data structure. I asked Seth about his approach to writing, and about his work in technical writing.

Let's start with an introduction.

I'm Seth Kenlon. I tinker with open source technology, and I often write about what I learn.

You've written a ton of technical articles about all kinds of topics, including shell scripting, programming, and Linux desktops. What is your motivation for writing about these topics?

My greatest motivation is my own interest in a subject. I tend to pay special attention to what I'm "distracted" by in life. That distraction is often the thing I'm most passionate about, whether I recognize that passion yet or not. Whenever possible, I follow most of my distractions to their logical end. Sometimes that takes years; I got distracted from film by Linux nearly years ago, and exploring it still is as fun as it was the first time I booted it. Other times, it produces a fun programming project or a seemingly random item of curiosity like an album of synth music, a card game, or rules for a wargame.

Whatever form a distraction takes, documenting the steps to reproduce it is a great way to reinforce what I've learned along the way, and to help others follow that distraction for themselves.

When someone's paying me to document something very specific, I have to focus on a challenge. My usual challenge is to explain a concept in the most efficient but effective way possible. The perfect technical document leaves no room for interpretation, is a pleasure to read, and is only as long as absolutely required. That's the challenge I try to meet any time I'm hired to write tech documents.

What is your process for writing an article?

Even when I know a topic well, research is always the first step. At the very least, I verify what I think I know about the topic. Are there different ways to perform a specific task? Is it effective to document every possible way to perform a task, or is it better to demonstrate a specific workflow? Or do I need two documents: one for workflow and one for complete documentation of every available feature?

In addition to that kind of thinking, I sometimes have to learn how to do the thing I'm writing about, too. That's tricky, because when you're the one documenting something for the first time, there are likely no tips on the Internet yet to tell you how it works. You have to talk to the programmer or designer, or you have to read the code, or you just have to figure it out.

I like outlines, but I admit I don't always write them down. When I do, they usually take the form of section headings with a sentence or two about what the section demonstrates.

I rarely change my first draft, because my real first draft was the outline. I do a lot of editing as I go, and I do an edit after the document is complete, but the end result is usually just a cleaner version of the first draft. No matter what, though, I always appreciate a good set of eyes to review my work before it goes live. A good editor is a real asset.

I'm referring purely to technical writing. Stuff I write for fun, like blog posts about my favorite tabletop games or movies, never gets that much forethought or review.

You've also worked in film. How did you get your start?

I was on a subway on the way to a gig, and I was reading a film journal to kill time. I recall the journal interviewed Phil Tippett and Joe Letteri, and they were talking about the render farm they'd built for a recent movie, probably the original Jurassic Park or Toy Story. They said it had changed the way they worked, because with Unix  you could have lots of computers access the same file to contribute to a render.

They were talking about a Beowulf cluster or something like that, but it was magical and utterly mystifying to me. I couldn't get it out of my head. I was captivated. I wanted to make a computer work without opening a video editor or 3D modeler.

Seven years later, I was working for Joe Letteri at Weta Digital as a Linux specialist.

What are your favorite tools and/or technologies for writing?

Currently, I prefer writing in AsciiDoc with GNU Emacs. AsciiDoc is a sort of scripting language for Docbook XML, which I enjoy and trust. Emacs allows for a lot of customization, and it's really flexible in how you can use it.

I find that AsciiDoc succeeds in all the ways Markdown fails, except in the way it looks. Markdown looks like "normal" text, and I think it feels very natural to read it. AsciiDoc looks like structured text, and sometimes is strange for casual reading.

For instance, this is a URL in Markdown:

Go to my [website](http:// example.com)

This is a URL in AsciiDoc:

Go to my http://example.com[website]

Markdown expresses the concept in exactly the way you'd write or say it normally, except that it insists that you use brackets and parentheses in a predictable manner. AsciiDoc bizarrely inverts the way you're likely to read the statement, and feels less structured for the lack of markup.