Yesterday I told the story of the photo frame template I built, and the wall that made me sad. I can’t claim I designed that image, because except for the backdrop I used, I followed someone else’s detailed, step-by-step instructions to make it.

The part that matters, though, was never the frame. What matters in that image is the detailed map of a nonexistent island chain. The frame just gives it context.

Working with Document Templates

It’s a big source of confusion (and misplaced frustration) for a lot of new Tech Writers, but Tech Writers don’t spend too much time writing. We spend most of our time searching for, learning about, and building up these frames.

This isn’t the first time I’ve talked to you about document templates. I’ve mostly talked before about how they save time and how to customize the moving parts in different writing programs, but this week I want to talk about how we choose the right template and figure out what to make those moving parts look like.

The Moving Parts

There are several key elements that go into any document template. The details change from one to the next, but this one set of pieces is essentially the definition of every document type.

• Page size and layout. Is it a standard 8 1/2 x 11 or is it cut to match the other paperbacks on your bookshelf? Are the pages oriented portrait or landscape? Or are they square?
• Text columnation. Is the text in one column? Two with a dividing line down the middle? Is one column reserved for special information, or is it just a broken page flow? How is the space on the page divided among the page’s columns? (That last question matters even if it’s single column, because that determines the page’s margins.)
• Heading format, frequency, and hierarchy. Does your document need any headings beside the title? Does it have multiple volumes? Does it have chapters? Do you need to break chapters up into sections? Are there predetermined sections that should always be included? Where do those need to be?
• Heading and paragraph styles. Once you’ve nailed down your heading hierarchy, how do you clearly convey it to the reader? Do you have multiple font sizes for the different ranks of heading? Do you use different formatting (like bold, italics, and underline) to differentiate them, or just whitespace?
• Required metadata and optional metadata. What information about the document (not the document’s contents, but the document itself) does your reader need? What’s recommended, and what’s critical to make the document work? Should your reader provide any (or all) of these items? (For each of them, a good template tells you what information is needed, where to put it, and how to format it.)
  • Document title
  • Subject line
  • Executive summary or abstract
  • Revision number
  • Author’s name
  • Author’s address, phone number, email address, etc.
  • Recipient’s name
  • Recipient’s address, phone number, email address, etc.
  • Publisher’s name
  • Publisher’s address, phone number, email address, etc.
  • Date the document was written
  • Date the document was signed
  • Date the document was published
  • Copyright statement
  • Trademark information
• Document structure. How should your document be organized? Does it need any of the following, and if so, what should they look like?
  • Front matter — whether it’s a Title Page, Copyright Page, Foreword, and Table of Contents, or just a one-inch letterhead — is usually a container for much of the document metadata mentioned above.
  • Body text is mostly governed by choices you made above, especially with heading hierarchy and styles. This is also where the bulk of your original content will go.
  • End matter often includes additional references (internal or external), and sometimes repeats critical metadata, but it almost never introduces new material.

By deciding which of these pieces to include and which to leave out, and establishing how to style each of them, you can shape a single bit of text into something that is immediately visually recognizable as a n0vel chapter or an epic poem, a business letter or a project status report, a blog post or a movie script.

Searching for Sample Docs

So now you’ve got a big long list of pieces, but how do you use that information? Well, if you’re a careful reader, you could go through that list and some of the posts I’ve published in the last month, and build a detailed template for Julie’s blogstory style (even though as a document type that’s basically just a name I made up).

You could do the same thing if you read somewhere that you need to write a query letter, and you’ve never heard of a query letter before. Or if you need to prepare a formal project report or a request for funding. If you have access to a document template, it often just looks like a half-written document, but if you know what it’s trying to define (that list above), then you know how to interpret the placeholder titles and the one-sentence chapters.

And there are certainly times when there is a standard way to prepare a document, but there’s not really any way to find a formal template. In that case, the best way to figure out how to write your document is to find two or three good sample documents, and reverse-engineer the template definition.

If you come back tomorrow, I’ll tell you how to find good samples and discover a new document template.