Discover key insights and techniques for effective, process documentation, with clear guidance from Jo Cook
I saw a Facebook meme recently that went a bit like this:
Me as a youth: Don’t tell me what to do!
Me as an adult: Would someone please tell me, in intricate detail, with timings, exactly what I’m supposed to do.
Good quality work often has a good quality process to guide it, so that there’s consistency, quality and clear outcomes. On a contract piece of work I was recently updating a relatively big process document and want to share with you key points of my approach for you to apply to creating or updating your own.
Audience
Firstly it’s knowing who the information is for. The document in this project sat in the folder of a particular business team, so we would assume it’s for that team. However this process relates to an “External Team” that contracts on specific projects, working with the “Business Team”, both of whom can access the folder. I’m part of the External Team, and I didn’t realise that the document was for me, as we have our own “External Team Folder” for our documentation. Confused already? So was I!
The current document, in the Business Team folder, had a lot of content, for both teams. My first job was to decide which team needed to know what for their work. I split that document in two as The Business Team needed a higher level view of the process and their responsibilities within it, but not the detail. Whereas the External Team needed a lot of the detail to do the work.
Top tip: Have different documents (or sections of a Wiki etc) for different audiences, to avoid overwhelm and provide the right level of detail for the role/task
If your documentation is part of a Wiki, Knowledge Management System or similar, the path and title may be explanation enough of what it is and who it’s for. If you are using something like SharePoint, Teams (which is often just a shell on top of SharePoint), Slack etc, then by having access to a particular team folder or channel, this might also indicate who the document is for. But it might not indicate it’s importance.
This document was originally called:
“Process for xxx work – Version 01”.
Yes, it says it’s the process for the work, but sat in a Teams folder with other documents, so it didn’t jump out as the thing to look at.
I made a very simple change and named the new version:
“Business Team READ ME FIRST – Process for xxx work – Version 02”.
This gave direction to people who were staring at a folder and not knowing what to do. I also did similar for the External Team version in their file location too.
Top tip: Follow internal naming conventions with regards dates, version numbers, and authors, but also function and ease of understanding of who needs what
Design
The look of a document isn’t necessarily the most important next step to take, the content is usually more important. I was working on an established document with a team that had some collateral, in other words images and a design look, so it was relatively easy to put on a front cover image, company logo and a nice big title to make it really clear upon opening what the document was about and who it was for.
I also wanted to tidy up the design of the document as I went. Both from a technical perspective (aligning tables, having the right paragraph breaks, consistent line spacing, font and size etc) as it removes the noise and clutter of an already big and complicated document and makes for a “Clean layout so information is easy to find”, as said by design expert Connie Malamad.
Top tip: It’s worth learning about templates, styles and so on in your application of choice, as it can make design and layout quicker, easier and more consistent
I did some relatively simple things, but they made for a cumulative impact on that easy layout. At the beginning of the document was a list of roles in the process (Manager, owner etc), with a paragraph description for each:
- I updated the paragraphs into bullet points under each heading
- I simplified the language as most people aren’t going to read the document like a novel
- I ensured the right information so it’s easier to scan, which helps the reader
Jayne Davids said in her content design article, “Images and videos offer a visual representation of the step or process. They give context, reinforce the information, and can enhance the learning experience.” So I added screengrabs from emails and systems to make things quicker and easier to process, recognise and remember.
Hopefully we all know that there’s empirical evidence behind this recommendation: “Pictures are generally more easily recognized and recalled than words, although memory for pictures and words together is superior to memory for words alone or pictures alone” from Universal Principles of Design (p152).
It’s worth noting that this research can be traced back to 1894 when Kirkpatrick reported the results of an experimental study of memory for spoken words, printed words, and real objects.
Top tip: Make sure that the images you include add something to the meaning to help the work and the recall later, otherwise it’s annoying noise
Colour is another huge area of design: “All you need is a handful of colours, between two and five”, says Andrew DeBell in his visual design article.
There were tables in the document with tasks in the process, and different roles were responsible for different tasks. I used colour, as well as text labels, to denote these differences and make it easier to scan through the process and find the area you are responsible for.
When selecting colours, it’s really important to consider accessibility and inclusivity.
Top tip: See if your organisation already has brand guidelines and either include them in your documentation, or perhaps find some templates already setup for you. The marketing or communications department may be able to help
Content simplification
I wanted to ensure that the documentation was easy to use, otherwise there’s no point to it. James Shields, in his accessibility article, says, “Use visual hierarchies for layout: Implement design features and formatting to draw attention to key parts of your content, to help readers with accessibility issues identify areas they need to concentrate on. This will also help them understand the order they need to read your content for greater context.” I’ve already applied some of this advice in the notes above.
Towards the beginning of the documentation I included a process overview so that people could get the big picture of what happens. In other documentation I found a diagram version of the information and included that too.
I also included tables of other summaries – of timings (eg do X within two business days), emails that are received (from process@system.com contains X information and your action is to X) and so on. These are handy references before the main detail of the document in a relatively complicated, and often changing, process.
Top tip: Think about people who are using your documentation for the first time and need to know new things, as well as for the hundredth time and just need to find information quickly. This will help you decide what to summarise, where and how
The detail
I’ve written a feature-length article already and not even gotten to the process itself! Luckily, it’s putting into practice all of the above. I had to check a lot of the technical detail to ensure it was correct. Some of it I knew as I was working in the External Team. Some of it I could find in meeting notes, some I had to contact various subject matter experts to explain or confirm.
This obviously all takes time and it’s worth having an approach for marking out things you are unsure of or that take time for responses. This could be tracking features and comments if they are in your application or even assigning tasks to others. At the time I was the only person working on the document for an initial overhaul, so I chose to use yellow highlighting as it’s bright and simple to use.
Some of the changes I made were to wording. The person who had put the document together before me had done a great job, however English wasn’t their first language, so I was able to enhance the document further for the English speakers using it. Such as changing this:
“<Work role> must fill in the availability form within one business day if they want a chance to get the work. When giving their availability <work role> should not only consider being available at the day and time of the project but also having the availability to fulfil the package (Project level 1 = xh, Project level 2 = yh and Project level 3 = zh).”
To:
“Within one business day <work role> complete the survey of availability, which will need to include:
* Project level 1 = x hours
* Project level 2 = y hours
* Project level 3 = z hours
If the form is not completed within one business day, or at all, the <work role> will not be put into the pool available for the work.”
I felt that the tone was more in alignment with trusting contracted specialists, as well as being laid out more clearly.
Top tip: Write rules and expectations in objective language to ensure a professional response
The rest of the document was more of the same – separating out steps, roles, functions and detailing them clearly in bullet points, numbered lists and linking to appropriate documentation.
Is there an end?
Whilst I had a finite time to rework this process, this kind of documentation very rarely has a conclusion as working practices change, projects update and roles fluctuate. It’s important that someone has overall responsibility for ensuring that any changes are reflected in the documentation and that appropriate people are made aware of those changes, after all, you wouldn’t want to make a rule change overnight and not let people know!
Is it a perfect document? Of course not. Some comments from the team were about repetitiveness and the length of the document, which had doubled. However that’s all part of an update, feedback and then reiterating the work to get to the best possible situation within the time and resources available.
Jo Cook is Editor of Training Journal and a learning specialist at her company Lightbulb Moment
