How To Format Your Documents
This is the final section of our 5 part series on documentation. Click Here to start from the beginning.
The most important thing to remember about formatting your documents is to make the document format HELPFUL to those people who will be using those documents. You also want to consider whether the best strategy is to create a new document that may be potentially unfamiliar to your team, or to revise a current, well-known document. The answers to three essential questions can help you strike a balance between these goals:
Every document, whether it exists in hard-copy or a digital space, has a cost. Some of those costs are direct: the time it takes to create and review the document, and train folks on the content of the document. Some costs are indirect: the cost of a long document vs. a short document, the cost to store a document (even as a digital file), and the cost to maintain the document to keep it current over time. To prevent overzealous documentation, imagine that every document you create has to be written on a $100 bill Sometimes you have to spend that $100, but would you be so eager to do so if you could revise an existing document instead?
Formatting Techniques and Best Practices
There are a lot of different ways to write a document and several best practices for formatting a document that make it easier for users to understand when, and how, to use it. In this section, we’ll break down the most important pieces of a document and provide an example of how to use each one. We’ll also point out where the content may differ based on the type of document (whether it’s a policy, procedure, or instruction).
Many believe that purpose refers to the purpose of the document when, in actuality, it refers to the purpose of the process being defined by the procedure. A more effective approach is to think of the “purpose” of a document as a mini-policy stating why that practice is important.
“This document defines how the Daily Inspection Report is completed, reviewed and submitted for approval.”
“The purpose of completing the Daily Inspection Report is to capture what was looked at, whether it was acceptable, and what actions were taken if not. That report must be reviewed by a supervisor and submitted to management for approval before it is formally recorded.”
“Scope” is not a mouthwash. (Okay, it is, but not when it comes to documents!) Scope defines what is, and is not, included in the document. It’s a common oversight to forget about writing what is not covered in a document, but this information is just as important - especially if you want to prevent readers from making incorrect assumptions about other parts of the process.
“This document details the preparation of chocolate cupcake batter.”
“This document details the preparation of chocolate cupcake batter. It does not detail the preparation of yellow or red velvet cupcake batter, which is detailed in procedures 345 and 346.”
3. Responsibilities & Authorities
It’s common to define responsibilities by title, however the best practice is instead to define responsibilities and authorizations by role. What’s the difference? As an owner, you likely wear multiple hats in order to keep your business going. Regardless of your title (Owner, President, Senior Manager, etc.) the role you are playing is likely to change at any point during the day.
A role is most directly tied to a business process. When creating a sales contract, you are in the role of “salesperson,” but when you are packaging up your product to ship to your customer, your role is “distributor.” Documenting responsibilities and authorities by role is important if there are multiple individuals with identical titles but different roles in the process being defined, or if you are planning on introducing new titles as your business grows.
The opposite can be true as well: you may have multiple people with different titles performing the same task from time to time. If you initially define the responsibilities and authority of a process by role, you will save yourself time down the road when your business grows and you don’t have to rewrite documents to explain who does what to new employees.
Another common pitfall is to write the details of the process. Keep this section limited to only what the responsibility and authority is, and do not include any activity. Write:
(Role) is responsible for...
(Role) has the authority to...
This section should also include who is responsible for the process, and who is responsible for maintaining and approving the document. Typically, this is the same person who is responsible for ensuring the process is described and followed as expected. (This responsibility is a rare exception to the role rule. Often, the person who is responsible for a process has both the title and role for that job, such as Department Manager.)
Mixing titles and roles
Adding more information to the section other than the definition of the role and the commensurate responsibilities
List roles instead of titles, and briefly describe the role’s responsibilities. Examples:
Buyer: Records all supplier requirements and prepares purchase orders
Sr. Buyer: Reviews and approves all orders prior to placement
Purchasing Manager: Maintains and approves this procedure. May also perform the role of Sr. Buyer
This is a list of tools and other resources needed for the process to happen as designed. The resource section typically identifies specific software, specialized tools, and points to other documents needed to provide input to this process, or forms used to capture outputs. It may also point to a common term and acronym dictionary for terms and shortcuts used in the document.
This section provides a detailed description of the process or policy outlined by the document. We strongly recommend including a high-level flowchart or swimlane diagram accompanied with detailed text. Best practice is to keep this section organized in logical steps. A good way to start this section is to use the “First/then” approach:
First, we do this….
Then, we do this….
Then, we do this….
A flowchart or swimlane diagram turns words into graphics and is capable of describing a process in fewer pages. In a future post, we’ll offer quick tips and helpful hints for creating flowcharts that can be dropped into a document quickly.
Using a lot of words to describe a simple process.
Writing in future or past tense.
Use active voice (“we do this” instead of “we will do this”). Remember, you are writing your documents to be used by your business today, not in the future.
Use roles instead of names or titles to allow the document to flex with any changes in the future.
When referencing another document, or an illustration in another document, provide the complete document name and illustration reference. If your documentation is online, include a link.
When using an abbreviation or acronym, verify that it is listed in the common term dictionary. If not, add it.
Records are new pieces of information generated as a result of following a process. In your documentation, make sure to list all records that will be created, and include key details on how to process them like:
Preferred format for the record (word document, spreadsheet, hard copy, etc.)
Where the record should be kept and for how long
Security restrictions, if any
We recommend documenting your record procedure in an easy-to-reference table like this one:
7. Measures of Success/Metrics
In the previous post of this series, Organizing Documents to make sense for your business, we discussed the importance of identifying measurements for your business practices to ensure your company is meeting its goals. The importance of including this section in every document is to pass down higher goals to specific objectives applicable at the process level.
The best way to address this section is to ask yourself, “How will I know if this process has done what I want it to do?” It’s also important to note that not every process requires metrics. (We’ll discuss strategy and planning in a future post, ). For now, consider whether the process you are currently describing is critical to the success of your business; if so, you need a performance metric in this section. Since deciding what metrics to include and exclude can be a slippery slope and is directly tied to what and how your company creates deliverables for your customers, we usually recommend including at least one measure of success that can be easily recorded for future evaluation. It’s a lot easier to remove a measure of success or metric than it is to add it later.
An effective best format looks something like this:
8. Revision History
Today, the majority of change tracking is handled with sophisticated workflow management tools such as SharePoint, Oracle, SAP and others. However, if you do not use a program like this or prefer to track your changes manually, we’ve created a quick table to show how you might do that instead. Revision history has four basic components as shown here:
This section captures a snapshot of the changes made to an example document and forms an essential basis for training, and retraining, employees.
We’ll go further in-depth on how to detail the information under “description of change: in the upcoming Document Control and Configuration Management series. For now, understand that this field should capture a succinct description of what exactly changed in the document to be helpful.
Revise Existing or Create New?
Now that we’ve examined the sections of your document, we need to discuss whether it is more efficient to create a new document or to revise an existing one. The tradeoff between revising an existing document vs creating a new document can be difficult to weigh. Sometimes, creating a new document is the best strategy to gain users’ attention to a significant change, such as the introduction of a completely new process. In other cases, changes to the finer parts of an existing process (for example, switching tools to perform the same task) are better suited for a revision to an existing process document.
Apply the KISS rule (Keep It Simple Silly) when considering whether you can revise something that already exists over creating something new. Besides the obvious redundancy of format embedded in each document that would need to be repeated in the new document, authors of new documents suffer the pitfall of not realizing - or not researching - other existing documents to confirm they are not repeating content that is captured elsewhere.
The perils of repeating content are twofold:
It takes time to write out documentation, and time is money. If you add up all the time spent on doing work that has already been done, the total cost might turn your hair white.
When the same piece of information is documented in multiple places, any changes must be made to all of them. Miss one, and suddenly you have conflicting documentation.
The solution to this is the creation of a large index that references every document and the information it contains. When content changes, you can now find all of its locations for updates. However, this too takes up an extensive amount of time - both the creation of the index, the time needed to reference it, and the time needed to make the actual updates.
Use your schema (see Post 3) to quickly review the scope of your existing documents to see if there is one most suitable for the new content you want to add. If not, write a new document.
Coming Up: Document Control and Configuration Management
Phew. We’ve now walked through the details of creating meaningful documents to help you run your business. These documents give you the basis for developing a world-class training program and for holding your employees accountable. The next thing to address in getting your business spiffed up is how to manage these documents when change happens. Please join us in a future blog series, Document Control and Configuration Management where we will dig into what happens when things change.
Thank you for joining us and if you’d like help with any of these steps, please contact us at Archimedes C&C!