All Posts in Category: Uncategorized
Just like any other business activity, technical writing can be boiled down to a process – a set of high-level steps. These five steps are Plan, Structure, Write, Review and Publish. These high-level steps are the common elements in virtually every technical writing project – really in any business writing project – big or small.
Of course, I’m not saying that all technical writing jobs are the same… as any practising writer will tell you, they certainly aren’t! However, in my experience every writer goes through these five high-level steps – even if we’re not conscious of it. Sometimes when we’re just muddling through on a job – or an experienced writer operating on autopilot – we still go through these steps.
It helps to keep the five steps in mind when you’re writing technical documents, so you can mentally ‘tick off’ your progress as you go – and understand what’s yet to be done. I’ve provided a breakdown of each of these five steps below – this is a good place to start if you’re interested in understanding more about the Technical Writing Process, or just want a ‘quick and dirty’ definition.
In my book, Technical Writing Process, I describe this process in full (together with the more detailed version of the technical writing process, which you’ll find here) together with a smorgasbord of other content (templates, tips, insights, etc.) to help you successfully manage your own technical writing projects.
STEP 1 – PLAN
‘If you fail to plan, you plan to fail.’
All projects need to be planned – at least at some level. Whilst you don’t have to go create a detailed Gantt chart for every technical writing project, it certainly helps if you answer some of the following questions before you put pen to paper. The results of this planning may be as simple as some bullet points jotted down in your notepad – or you may find that simply going through this as a mental exercise is sufficient.
When you’re planning to write technical documents, you should ask yourself:
- Scope – How many documents do I need to write? What are their key characteristics? Am I going to publish them in multiple formats – if so, are there any production requirements I should be aware of?
- Timing – How long do I need to schedule for review cycles? What’s the final deadline?
- Process – What are the high level steps that I need to follow to create the documents?
Along with these basic questions (which apply to almost any project – not just technical writing) there are some specific writing-related questions that you’ll need to consider in your documentation project:
- Audience – who am I writing for? Do they have a sophisticated command of language? What are their education levels?
- Reviewers / Subject Matter Experts – these are the people who’ll lend their technical expertise in the creation of the documents and review them for accuracy
- Existing information
- Style guide / templates
If you’re just writing one or two documents, you won’t need to spend much time on detailed planning. However if you’re creating dozens, hundreds, or (heaven forbid), thousands of documents, then putting some thought into these questions up-front will save many a wasted hour later on.
In my book, Technical Writing Process, I’ve provided detailed explanations for activities described above. I’ve also provided ready-to-use templates to support the steps:
- Documentation Plan
- Documentation Timeline / Schedule
- Deliverables Matrix / Worksheet
- Status Tracker
These templates are essential for more complex projects. Even simple projects can benefit from a simple Status Tracker (in fact, that’s the one essential tool I use on every single project).
STEP 2 – STRUCTURE
A structure is the backbone of your document – the hierarchy of headings that define the logical order that it will progress. Structure is absolutely essential to successful documents, and it’s something that you should develop before you start writing. A well-structured document is one that has had thought go into it beforehand, which means you’re less likely to need to rehash it later on.
It’s important to understand that structure isn’t a straightjacket – it’ll evolve and change as you write and review the document. After you publish, you may end up with a very different-looking document to the one you envisaged – that’s perfectly normal and there’s nothing at all wrong with it!
There are a number of common structural approaches when it comes to technical documents:
- Narrative structure – The traditional approach – intro, body, conclusion
- Process-based structure – Common in technical documentation such as procedures and user guides
- Library structure – A collection of articles on a common topic, loosely structured
- System-based structure – Describing the components of a system such as an auto manual
Whatever approach you choose, you’ll need to work with your subject matter experts to understand how the structure you’ve developed will accomplish the purpose you’ve set out to do – whether it’s explaining how a product works, how to carry out a procedure, presenting information in a tender or sales document, and so on.
In my book, each of these approaches is explained in detail, and I’ve devoted particular attention to the process-based approach as it’s the norm – and best practice – in so many technical documents.
STEP 3 – WRITE
Writing is where you convert your bare-bones table of contents and notes into a series of drafts, culminating in a draft that’s ready for formal review. Contrary to popular impression, writing is only about 20-30% of the process in a well-planned document – much of the effort goes into planning, structuring, and reviewing your work. In fact, the more time you spend planning and structuring your work, the less time you’re likely to spend on writing.
There are a few time-honoured (as well as some new) techniques that technical writers draw on:
- KISS (Keep It Simple, Stupid!)
- Plain English
- Five Ws (and One H)
- Inverted pyramid
- Verb-noun structure
- Active voice
These techniques will help you write better documentation – documentation that your audience finds useful, engaging and a pleasure to read. Of course, in order to apply these techniques you need to have a decent grasp of the English language.
(Sidenote: Teaching you to write isn’t what a technical writing process – or my book, Technical Writing Process – is about. There are plenty of resources available if you want to improve your writing. The technical writing process is about is how to apply your writing and project management skills to the task of producing high quality documents in a way that hits the mark, resonates with your audience and achieves your deadlines.)
Writing well is one thing – but if you want to produce good documents, you’ll need to engage your subject matter experts. If you’re a professional writer like me, you usually rely on a subject matter expert – someone who’s an expert in a particular field – to lend their technical expertise to whatever it is you’re writing about.
At this stage, engaging your subject matter experts means a lot of informal one-on-one discussions – or even workshop-style if you have a large group of them. At this stage, you should be asking your experts to contribute raw material, review and / or test what you’ve written and so on. Remember – at this stage, it’s all fairly loose and informal – the formality comes in the next step, Review.
The final part of writing is formatting and laying out your draft before you launch into the formal review process.
In my book, I discuss the Write step in detail, including the techniques described above. I also include a number of other important aspects such graphic design tips for writers and how to establish and build good working relationships with your subject matter experts.
STEP 4 – REVIEW
I like to think of review as the polishing stage. It’s where your document gets the trial by fire, so to speak, of having others formally review it, as well as undergoing another very important task – editing and proofing.
(Sidenote: Editing and proofing is in itself the topic of numerous books. In my book Technical Writing Process, I’ve provided a practical, no-nonsense editing model – The Seven Levels of Editing – that’s suitable for technical or business documents.)
If you haven’t already done so, you’ll now need to define who’s responsible for reviewing what (also called a Review Matrix), or validating it if you’ve been proactive and defined it during the planning step – which you should aim to do.
In the Review step, there are a number of discrete activities going on (depending on the type of document being written):
- Review by subject matter experts
- Testing a procedure / instruction to make sure you / a subject matter expert can follow the steps
- Peer review by a colleague
- Editing and proofing
The point of all these activities is to apply the appropriate level of quality control to ensure your document is accurate, useful, usable, and so on – in other words, good enough to publish. It’s not uncommon for documents to spend most of their time in the review step – and by the end, they can be completely unrecognisable compared to how they started.
Review also involves an element of writing – documents will be reviewed, then revised. High-profile documents – the ones where it really pays to put the effort in to making sure they’re perfect – will be reviewed and revised many times before they’re ready to publish.
The final – and most crucial – aspect of review is sign off. This is the point where both you – as the writer – and your reviewers are satisfied that your document is in a fit state to be published to the world at large – whether that’s your team, company intranet, or the entire world!
Review was my favourite chapter to write in my book Technical Writing Process, because this is where so much of the ‘goodness’ gets added to documents. In my book, the Review chapter features the following:
- Levels of Editing diagram – Defining the different levels of review such as proofreading, copy editing, structural editing, and so on
- Editing Checklist – A checklist that guides you through the different levels of editing
- Editing Sheet – A document that professional editors use when editing a large and complex document
- Review Log – To track the feedback received and actions taken to close each item out
- A sample Message to Review Team
I’ve also covered topics such as peer review and testing, as well as explaining in detail how to conduct – and get the most out of – the review process, including final sign off.
STEP 5 – PUBLISH
Publishing can be a complicated process – or it can be extremely easy. Publication is where writers manufacture and launch the final product. This might be as straightforward as emailing an approved document to your manager, or uploading it to a content management system or intranet. On the other hand, it might involve some fairly complicated logistics.
I’ve personally been involved in projects where production involved graphic design, translation into 40+ languages, production of multiple regional variations of the documentation, preparing ‘docupacks’ for shipping to multiple regions worldwide… this sort of thing is a real logistical feat, and it’s something you should consider early on in the process – preferably whilst you’re still planning a document. Steps such as graphic design, translation and print production can involve substantial time, effort and cost.
In my book, I discuss publication, covering many common tasks such as performing final checks, communicating with stakeholders, and establishing a version control system that’s suitable for the majority of technical documents. It also includes discussion of more advanced scenarios such as print production and translation.
The technical writing process is supported by activities and tools
My book, Technical Writing Process, explains each of the steps above in detail, linking each high-level step with the detailed activities and tools needed to accomplish them. This is shown in the full version of the technical writing process diagram:
By applying the steps, activities and tools in the technical writing process – and customising it to suit your project – anyone with a sufficient level of writing skills can successfully create technical documentation, or learn how.
Here’s what my friend, colleague and reviewer, Keo Phetsaya – Engineer and Project Manager – had to say about the book:
‘This book serves as a great reference to someone tasked with the technical writing aspect of a project. It would have saved me much heartache and a considerable amount of time if I had this information at the start of my project. Your templates at the end of the book would have been really useful to me at the time.’ Keo Phetsaya