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)?
If you’re the only person you need to talk to, go straight to step 4🙂
- Talk to the people who need the document. (Stakeholders.)
- Get a room.
- 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.
- Grab a whiteboard, or a wiki, or a piece of paper… whatever is available.
- 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.
- 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:
The 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.
Thank you to Fag On Foss for suggesting this blog post.
And to Ryan for the skeleton.