Skip to content

The Shape of a Document

When you do it right, good writing is easy as pie. (Photo courtesy Joebeone at Flickr | CC BY 2.0)

When you do it right, good writing is easy as pie. (Photo courtesy Joebeone at Flickr | CC BY 2.0)

Last fall I taught my first college-level writing course — Technical Writing at Oklahoma Christian University (my alma mater). My class consisted of a bunch of computer science and information technologies students, and a handful of English majors. It was an interesting mix.

I wasn’t out to teach them how to do my job. I did ask, first day of class, how many of them had considered becoming a Technical Writer after graduation. The answer (quite predictably) was none. When I got around to asking what they were planning on doing, every one of them named a profession that would require some proficiency with technical writing, even if it wasn’t their main job description.

So my goal wasn’t to teach them every aspect of technical writing, but to teach them what technical writing is, and why they should care. The answers I came up with became the seeds of this website, because more and more we all have to write, and we’re all eventually judged by what we write, and it’s really easy to get it right if you just know what to look for.

One of my favorite classes, and probably the most effective demonstration of that concept, was the third week of class. I came prepared with an outline, a handful of visual aids, and a bit of a sense of mischief.

My Haiku

I started the lecture with the first of the visual aids. It was a Notepad document, some plain text with no formatting whatsoever — just a bunch of words. I did leave in line breaks and punctuation, but I dropped everything to lower-case to increase the impact of the message.

So this is what they saw:

schumann’s resonance

headgear for grasshoppers

eyes like headlights


october 5

9:00 pm

p. j.’s


I said, “Anyone know what this is?”

One of my Computer Science majors said, “A haiku?” I almost laughed at that. I’d actually had, “Gibberish? A poem?” in my own notes for possible student guesses.

I just said, “What about this?” and opened the second document.

the jackpot

10:00 pm


eyes like headlights


the remember

january 5, 2008

Somebody said, “An advertisement, maybe?” I heard whispery voices treading dangerously close to the right guess, so I went ahead and put up the third document.

eyes like headlights

cd release party

debut album

there’s no us in evolution

5909 johnson drive

mission, kansas

with left on northwood and rettig

friday, october 26

the mission theatre

all ages 21 to drink

That third line gave it away, and I said, “What I’ve got here is the text from a bunch of band flyers. That first one looked like complete nonsense when I showed you just the unformatted words, but you’d recognize the information instantly if I showed you this.”

Band flyer for Eyes Like Headlights at P. J.'s

Band flyer for Eyes Like Headlights at P. J.'s

The point of all that? I told my students then, and I’m telling you now, the words that go on a band flyer don’t mean a thing until you put them in the shape of a band flyer.

Document Types

I talked before — a long, long time ago — about document types, and what they offer. As a writer, approaching a known document type (especially when it’s a template) makes your job easier. Instead of a blank page, you’ve got a form. Instead of a bunch of information, you’ve got answers. Everything you need to say already has a nice, clean place for it, and it’s easy to tell what you need to do, and when you’re done.

Doesn’t that sound nice? It’s the secret ingredient of Technical Writers everywhere. It’s how we survive all the documentation requirements and ridiculous deadlines they throw at us. We never start from scratch. We always have a map.

There’s more to it than that, though. As writers, these document types sometimes feel like shortcuts that were invented to make our lives easier, but it’s never about the writer. Technical Writing is always about the readers, and document types have a lot to offer the readers.

Take a standard business letter, for instance. Once you learn the format, it tells you (the writer) which information to include. How cool is that? But its real purpose — the reason it’s so important for you to get it right — is to act as a map telling the reader where to find the bits that interest him.

A recipe card is an even clearer example, divided into sections for ingredients, preparation instructions, and serving directions. All of that information could be written out in essay form. It could even be told as a narrative story:

When Mary wanted to bake an apple pie, she started by going to the grocery store and picking up two pie crusts, a half-pound bag of flour (even though she’d only need two tablespoons of it for this recipe) and some ground nutmeg. She already had some of the ingredients at home, including more than enough sugar and salt, and a whole batch of fresh-picked apples!

That’s the same words, but they don’t serve the same purpose. Readers have to work harder to get the information they need (like ingredients for a shopping list, or preparation instructions when they’re double-checking to make sure it doesn’t burn). In other words, just like with the band flyer, when you put the core elements of a recipe down in the expected format, the shape of a recipe card adds information to your document.

Learning Your Shapes

So what’s the point? Nobody’s going to collect their recipes in short story format, and nobody’s building band flyers single-spaced in Notepad!

The problem is…some of us are. Some of us are writing essays (or short stories, or abstracts, or SEO-optimized outlines) when we should be writing blog posts. Some of us are writing blog posts when we should be writing short stories. Some of us are writing casual emails when we should be writing business letters (even if we’re delivering that business letter through an email client).

It’s easy, when you’ve got to convey some information, to immediately reach for the document type you’re most comfortable with. Maybe that’s textspeak, or 140-character paragraphs. Maybe that’s 10-page papers, dense with context, even if your only purpose is to announce dinner plans for Friday.

I said in the intro to this article that we’re all writers, and it’s really easy to get it right if you just know what to do. One of the things you need to do, every time you start to write anything that matters, is stop and consider your audience. Stop and think about the readers who are going to be looking at the shape of your document, trying to spot the bit of information they need.

Then figure out where it’s supposed to be, and put it right there. Easy as pie.

One Response to “The Shape of a Document”

  1. Sean Sanders says:

    Always happy to provide inspiration for you.