Developing Team Documentation that Matters
Admin note before we get started: I’m an analyst and will use analyst throughout this article. Feel free to replace the word with “doer” if “analyst” doesn’t describe what your team does.
Let’s talk about building process documentation, training material, and work instructions. Generally, there are two camps of thinking here: 1) documentation is a useless checkbox requirement, or 2) here is a 100-page dissertation on this process that is full of really big words but doesn’t actually say what your people do. Both approaches leave you without anything actionable for your people.
In my career, I have seen one team with documentation that was actually used regularly by analysts. That team had a forty-hour block of newcomer training material that took analysts through real-world data, a roughly 80-page work instruction that provided a step-by-step walk-through of nearly every process our team did, and an overarching standards document that was nearly 70 pages and included standards for our analysis, products, and communications with external groups. Okay, that sounds overwhelming. But all of that wasn’t created overnight, and some sections were a simple paragraph or two describing a quick task (e.g. how to set up the team mailbox in Outlook).
You’re probably asking yourself- how in the world do they maintain up-to-date documentation with the painstaking team reviews, tech writer sessions, and leadership approval signatures? Simple, we didn’t. Our documentation was considered living documents, and they were frequently updated and tweaked as we got grew and learned. Policy documents should be signed. Work instructions and process documents should not. Having a working Word draft and a converted PDF to show the authoritative document at any given time may be needed for some teams- but we generally just worked from the Word document. And we did so regularly.
So, let’s get started. I believe that teams should have four primary sets of documents:
Concept of Operations (Vision/Mission Statement, Team Structure, Services, Functions; signed PDF)
Team Standards Guidance (SG) (Word doc; unsigned and living)
Team Work Instructions (WI) (Word doc; unsigned and living)
Initial Training (PowerPoint; unsigned and living)
I won’t get into too much detail about your CONOPS (high-level policy document). I believe this document should outline your team’s mission statement, how it fits into the overall organization, how it is structured internally as a team, and what its primary functions are to support the greater organization. This document is the only one that I recommend for signature and should undergo a thorough review process by executive leadership to ensure that the team aligns with their strategic vision of the organization. Get it written- probably 20 pages or less if you can- get it reviewed, signed, and shared with the team and senior managers.
Building the Foundation
Now that the high-level strategy is figured out, it’s time to write documents that matter. Stuff that changes what and how your people do their keyboard magic.
The best place to start is with what you already have documented for processes. Review each existing document and cut & paste the material that is discussing policy and standards into the SG.doc and step-by-step process stuff into the WI.doc. Start adding Headings from Word’s Style section to group sections of the documents, as appropriate for your material. For example, your WI.doc may have a section for “KPI & Metrics” with subsections that outline the specific click-by-click steps to pull metrics from different systems or processes. If the existing document includes screenshots, toss them in the WI.doc and into a set of slides for training material. (Note: I generally only create slides for “primary tasks” where the majority of the team needs to be trained). Once you have parsed your existing documents, put all of the old files in an Archive folder- do not delete them just yet.
PRO TIP: Your Table of Contents (ToC) is created auto-magically by using Words Heading Styles, and it also shows up in the Navigator window for quick jumping around in the document.
Now it is time to plus-up your documentation with usable material. Host a quick 30–60 minute meeting with the team and evaluate the Table of Contents- NOT THE MATERIAL ITSELF. Based on the ToC, identify what other sections and subsections are required. Don’t worry about who will be writing these sections just yet. Just ask “what else do we do that we don’t have covered here?” Once that list is updated, identify what are the primary tasks that your team does. Prioritize these sections for development. You may be tempted here to focus on building out tasks that have leadership attention and impact- and granted one or two of these tasks may deserve priority attention. However, the primary tasks that your people do every day are like the foundation of your house, and this is where your priority should be. After all, it doesn’t matter if you show leadership the fancy granite countertops (your shiny metrics and KPIs) if your foundation is hot garbage. I truly believe that KPIs and metrics are a byproduct of well-developed and executed processes. If it is painful to pull out quality measures for your team, you have a foundational problem in your processes and/or systems. I say all of that to say, focus on your team’s primary tasks first.
PRO TIP: Focus on your team’s primary tasks first.
Adding Support Structure
The next step is to identify your smartest person on each of the prioritized primary tasks. We’ll call them your Subject Matter Expert (SME) for that task. They will sit down with a junior analyst and train through the assigned process. During the training session, the senior analyst will take ROUGH notes in the WI.doc on each step they take and dump screenshots into PowerPoint of any major steps or system screen changes. These notes and screenshots should be rough notes that the SME will clean up after the initial training session is completed. Clean-up should include adding circles and arrows to call out specific areas of interest (e.g., “Click Here”).
Let’s use a real example here: creating a Medium post. On the left, you see what the Medium SME writes in WI.doc, and on the right side are the screenshots in PowerPoint.
Work Instruction and Training Material Development
You now have a 50–60% solution that requires a bit more shoring-up to be a firm, usable document for new analysts. Now we have the junior analyst run through the process a few times. They are asking questions as they go through the steps, and these questions become new requirements for the senior analyst to expand the training material and work instructions. For example, the junior analyst asks, “What button was it that you clicked to create a new story?” The senior analyst looks at his screenshot in the training material and adds a red circle to the slides around the “New Story” option in the drop-down. They may also add this screenshot with the red circle under Step 3 of the work instruction to draw attention to the button. Maybe the junior analyst asks, “Why did you say we must do this step before that step?” The senior analyst adds an explanation as a text block or standalone slide that explains the “why” of the procedures within the training slides. This explanation may make sense in the Standards and Guidance document.
Notice that no single document captures everything. This is to keep things simple and effective. If you add too many explanations and standards to a Work Instruction, you quickly lose the step-by-step feel. If you add too much “step-by-step” to your slides, you quickly get a really boring deck and analysts that are able to follow a process but unable to deal with deviations from the SOP.
Benefits of Analyst-driven Documentation & Training:
So I’ve outlined how analysts can drive your documentation and training development efforts. Let’s talk about the traditional approach to documentation and why you should take this analyst-driven approach instead.
The traditional approach- at least in my experience- is that organizations realize that they have a knowledge management issue or an inspection coming up and they throw technical writers and process analysts at the problem. After all, what problem isn’t solved by simply throwing more resources into the mix? (note: that’s my sarcasm font). The technical writers and process analysts schedule meetings to get basic introductions to the team. Follow-up meetings get into high-level discussions of processes. Deskside meetings are scheduled so the process analysts and tech writers can watch the analysts do their thing. The process analysts and tech writers go off to generate some Visio diagrams and high-level documentation. A follow-on meeting is scheduled where the process analysts and tech writers brief the analysts’ leadership- often without the analysts present- and documentation makes its way through the finalization and approval process. A year or two later, the team has documentation that the analysts don’t use sitting on a SharePoint they don’t even know about.
Conversely, I have been on teams that adopted the analyst-driven process discussed above. The timeline looks like this: the team lead identifies they have a knowledge management problem. They call together their team and assign someone to conduct a quick inventory of all of the documentation and start the separation process into a CONOPS, a WI, an SG doc, and training slides for a discussion in a week or two. The team meets, assigns out development responsibilities. The senior analysts immediately schedule time with the junior analysts for that day or the next day. WAIT- what about daily ops? They are still doing their daily ops while developing the documentation. The impact here is minimal and will be recouped by not having to step away for separate training sessions. After a month of working this method through multiple processes, the team likely has 70% of the major and minor tasks roughly outlined and captured in training material. For the next 2–3 months, senior analysts add to the documentation as questions arise. If an analyst asks “how should I write this ticket for escalation?”, the Senior Analyst can write a quick template for that ticket and add the template to the SG.doc for future usage. So using this method, you have a 70% solution within a month or two of starting and you have maturing documentation and standards within six months of beginning the project.
Here are some other benefits for this method:
Everyone is trained to a standard within the team.
New analysts know what they are supposed to do in a specific task.
Documentation is updated regularly to address new capabilities.
Documentation is built using real-world data, so the processes are immediately applicable to new analysts.
Analysts train with real-world material, so operations are not impacted by losing senior analysts to training time.
In my previous experience, my team actually saw an increase in productivity across the entire team during week long training sessions. This was because the entire team was able to clear their calendars to focus on training, and we used real-world material, so we were publishing actual products by the end of the week. This method works.
Audits and Inspections
When I was still on active duty, I was part of a large headquarters unit that bombed a pre-inspection dramatically. It was ugly. I had just returned from a six-month TDY and was put in charge of company ops (similar to a COO in a company), which meant that I was put in charge of fixing all of the low performing areas of the unit. Within ten months of applying the above method, we had a follow-up inspection, and we smoked it. The inspectors actually asked for us to sanitize our unit docs so they could send them to other large units as templates for their own documentation.
The point is that the auditors did not require signed work instructions and standards documents- all of our policy documents and Memorandum for Record (Army loves their MFRs!) were signed by the commander. While I’m obviously not an auditor nor inspections expert, it simply does not make sense to me that step-by-step type documentation or training material requires any form of finalization or signature for an inspection or audit. If I am wrong, I am happy to discuss because I truly appreciate learning from others and collaboration. I’ll post this to LinkedIn and Twitter, so pick your favorite flavor for discussion.
I highly encourage organizations to focus on living documents that are built and managed by their teams without the stress of worrying about excessive review processes. Focus on what matters and empower your teams. Best of luck.