How to kick off a document

A couple of days ago, a colleague asked for some tips on getting started with a document. Here’s the plot: You know you need a document, and you need it fast. You’ve got all these ideas and requirements buzzing around in your head. How do you get them down on paper (or wherever)?

The kick-off:

If you’re the only person you need to talk to, go straight to step 4🙂

  1. Talk to the people who need the document. (Stakeholders.)
  2. Get a room.
  3. Pull in the people who have the knowledge or skill that you must put into the document. (SMEs, or Subject Matter Experts.) If you’re the only SME, you’re very lucky.
  4. Grab a whiteboard, or a wiki, or a piece of paper… whatever is available.
  5. Create a skeleton of the document:
    • Write down the main topics that the document must cover. These will eventually become your page names (on a wiki) or your chapter titles. Don’t worry too much about sequence at the moment.
    • For each of the main topics, write down some bullet points summarising the content of the topic. These will become your section headings. Don’t worry if you’ve duplicated some content. That will sort itself out later.
    • Now try some sequencing. If you’re online, you can drag and drop to put things in the right position. Otherwise just draw circles and arrows.
  6. If there are other people in the room, you can now say ‘Thank you, and see you later’.

Polish and review:

Tidy up your skeleton. Make sure that:

  • each bit of information is in the most logical place, as far as you know
  • there are no loose bits
  • chapters and sections are in a logical order

Ask your stakeholders and SMEs to review the skeleton document.

Now you can start filling in the detailed information. It’s an iterative process, much like systems development. Your document will grow and change until it meets its requirements.

An engineering approach:

Skeleton by RyanThe above procedure is a simple, effective way of starting a document. It assumes that you already know quite a lot about the requirements for that document.

But what if you’re starting from scratch? Perhaps you don’t know your stakeholders, the medium in which the document will be written, your audience, or your subject matter. Maybe you don’t even know how many documents you need. You may be starting out on a major documentation suite.

For those interested in an engineered approach to documentation, there’s a very rewarding and thorough methodology called ‘Instructional Design‘. It was developed for the US military. Here’s what Wikipedia has to say. And here’s an introductory guide.

The Instructional Design methodology was created principally for training and educational documents. Much of the methodology is plain common sense to a technical writer. But it’s good to see it formalised.

Credits:

Thank you to Fag On Foss for suggesting this blog post.

And to Ryan for the skeleton.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 1 October 2007, in technical writing and tagged , . Bookmark the permalink. 2 Comments.

  1. I like this skeleton analogy – very October-y if you celebrate Halloween – or I guess it is Guy Fawkes Day for you?🙂

    I find that if you don’t even know if the thigh bone is connected to the hip bone, it helps to step back and do the task analysis that Instructional Design prescribes.

    Great post. I found you through the new WordPress tags – we’re part of a handful of tech writers blogging about tech writing using WordPress, yeah!

  2. Hi Anne, Great to hear from you! We do Guy Fawkes and Halloween both😉 I’ve wandered across to your blog. You have some very interesting posts. I’ll definitely pop round more often….
    Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: