Best practices on process documentation
From the basics up to models and legal compliance
Why would you do it?
You probably have asked yourself this question. Why should you invest time in writing it down? Because you don’t know what you don’t know.
Have you ever had requests from other departments that you feel like bureaucracy? It happens because you don’t know why they need this information since you don’t know their processes.
On their side, they don’t know which things you already do that could provide them with the same information. Some of your team members may also not understand the activities performed by other team members, so they can’t improve what they do to better support work done downstream.
I’ve seen teams that would sometimes test before doing code reviews for lack of a process. Imagine that!
So if you want to start thinking about global optimizations (since local optimizations may be detrimental to the overall performance), you need to have an overview of who does what, how, what they need, and where it is used (so you can also identify the actual bureaucracy and remove it).
Don’t stop at the diagram!
Many people like to document in a simple diagram. Create some activities with just the names and be done with documenting processes. As much as it provides an overview of what happens, it doesn’t help anyone much. I think that’s why people do it and let it accumulate dust in a corner somewhere. The real value comes when people:
- Onboard faster because they can read how to do things;
- Know what they will need (tools and resources are identified) and which resources your company pays for and nobody uses;
- Learn how each activity’s product is used in the following activities.
They will learn it from the activities descriptions. What is not used should be eliminated, but be aware that it may be used in another process. - Understand how they can adjust (tailor) the process to particular situations (directives);
- Know what shouldn’t be touched without approval, sometimes because of regulatory and legal requirements compliance (policies);
- Are aware of which data needs to be collected on which activities (to measure the performance of the process).
You will still need a diagram; it’s hard to read lengthy documents and to trace the subsequent activities, especially when there are forks and parallelism.
If you are documenting Software Engineering Processes (may it be QA processes, Development processes, etc.), you have two alternatives:
and:
Most people are more familiar with BPMN, so that’s what I tend to use the most.
If you are looking for friendly tools, you can consider the Eclipse Process Framework (free) for SPEM, Bizagi Modeler for BPMN (free, and the one I use the most), or Enterprise Architect (paid) for both.
What should you capture?
Aside from the flow in the diagram, with the decision points, parallelism, clear start, and end elements, you need specific attributes in your activity. I’ll list the basic ones here:
- Name: It should be something simple, a sentence at most. If it’s a question, it’s a decision, not an activity. If it doesn’t produce or modify anything, it’s either a step or a decision, not an activity. Activities will change or produce something. The name should identify what the goal of the activity is.
- Description: This is where you describe what is done. It is where you determine the steps to execute the activity and valuable links to guidelines, specific policies, standards, references, and external documentation.
- Responsible: This is the role responsible for executing the activity (which can be delegated). It’s a role, not a person.
- Participants: These are roles that may be involved (consulted, informed, or play some part) in the activity’s execution.
- Tools and resources: What will people need to do it? IDE? Issue tracker?
I’ll give you a very nice tip: Don’t name the tool in your process. If an IDE is required, say IDE. Use categories. You can have a separate table where you list your tools, where to get them, how to install them, etc. It’s much easier to maintain this way. - Required artifacts: These are artifacts that were produced in previous steps, as well as templates to build new ones. These artifacts may be just read or even updated.
- Produced artifacts: These are the new artifacts that were produced and artifacts that were modified or updated. If they were changed, they should also have been listed in the required artifacts.
Tip: If a produced artifact is not used anywhere, remove it. If the activity doesn’t produce anything, remove it.
As long as you have a diagram, you don’t need to document the pre and post-activities. ;-)
If you like this post, please share it (you can use the buttons in the end of this post). It will help me a lot and keep me motivated to write more. Also, subscribe to get notified of new posts when they come out.
Identifying the activities
Identifying the activities requires deep knowledge about each area (development, QA, requirements, etc.). If you are not familiar with these areas, you should identify the SMEs in the organization.
Note that they may not have the experience in identifying and mapping the processes, though. In software engineering, I recommend using popular references as checklists to identify what your organization does. Some of the best references are the CMMI or ISO/IEC/IEEE 12207:2017 for software development and ITIL or the ISO/IEC 20000–1:2018 for IT services.
These models and standards will tell you the outcomes of each process area without telling you how to achieve them. So you can use them as a guide: if you achieve that outcome, you must have an activity or a set of activities for that.
Unified processes
Once you have involved SMEs and checked up models and such, you must have realized different process areas. It’s not organizational processes, and it’s not team’s either. I’m talking about “knowledge areas,” like Requirements Engineering, Quality Assurance, Technical Solution, etc.
Following multiple partial processes that go back and forth with each activity is exceptionally messy and error-prone. Write unified processes with all the different areas involved. Add a label to each activity to flag the process area if you want to. It will likely be helpful to determine who should be involved in improvement discussions or the best way to support some compliance requirements.
Measurement and data collection
If you have KPIs or use any other strategy to measure the performance of your processes (e.g., GQ(i)M), you will want to mention in the activities that produce the data which data needs to be collected, how, and where. This will help you ensure consistency in your measurements. Not only does it help people remember to collect, but it also helps different people to collect the same thing at the same moment.
Process tailoring
Together with the process, you might want to define adaptation directives. This will tell the staff how to adapt the process to specific situations. Think about it as “the best practices in specific situations.” If you have to adjust the process to work in scenarios such as (non-exhaustive list):
- Requirements are too volatile.
- The client is not familiar with Agile, open scope, etc.
- You are not working on an Agile process.
Write down what worked best, associated risks to watch out for, and the impact on the process performance for each activity that needs to be changed, removed, or included.
Models and compliance traceability
Many companies are subject to regulations, have legal concerns, or even legal requirements (e.g., SOX). Some other companies adopt international standards (e.g., ISO/IEC/IEEE 12207:2017) or maturity models (e.g., CMMI).
Now that you have documented your process adequately (BTW, both CMMI and ISO 12207 will tell you to document it), and that you need to ensure compliance one or more models, standards, or regulations, you need to make sure that:
- If a publication (regulation, standard, or model) gets updated, you know which activities you need to adjust.
- Suppose there is a process improvement initiative (from a team due to a retrospective meeting or from the organization to improve KPIs or reach OKRs). In that case, they need to know what they need to request approval before changing.
This can be done in-process or in an external document (which I prefer). Both have pros and cons.
The in-process approach is when you reference the requirement that a specific activity supports in the activity description (or a separate field/attribute). It will reference an indexed topic (Regulation X, Paragraph Y, Clause Z) or a combination of page/paragraphs. Don’t forget to note the version of the publication. This makes it easier when people need to make improvements to the process.
The external document will have references to your processes and activities paired with the references to the publication. This makes it easier to scan for activities that need to be adjusted because of a publication update. It will also help auditors tremendously. ;-)
Best practices in process documentation
So, you know what to do, and you are ready to get your hands dirty. Which are the things you should consider?
- Abstraction level: Make all your activities the same abstraction level. Don’t make an activity so large that it could be a subprocess next to an activity that has one single atomic step.
- Who executes it knows it best: Ask the current executors to review what you have written.
- Process boundaries and tug-of-war: Don’t “finish” the process and start a new one because there is a team hand-off. If you are executing similar activities or if there is just one goal at the end, make it one single process. E.g., if one team develops part of the solution and another team develops another part, it should be one process because the goal is to build the product. However, if one or more teams built a product and now there’s a hand-off for product maintenance/support, you have two different goals that separate teams will perform. Even if the same team supports these two goals, you should still have two separate processes. Define your processes goals to determine the boundaries, don’t let your organizational structure dictate it, or you will end up with a tug-of-war situation.
- Inter-processes requirements: Ensure that each process produces all the artifacts the other processes require. That means each process may determine requirements for preceding processes.
- Accountability: One activity has ONE role responsible and accountable for executing it. This role can delegate the responsibility of executing the activity, but not the accountability. So that role is accountable for making sure that the activity’s execution.
- Produced artifacts: Activities produce something (new or updated/modified). If you have an activity that doesn’t produce anything, it could be a decision, a step belonging to another activity, or it may not even belong to that process. It’s also possible that it may not be needed, and you can cut the wasted effort.
- Institutionalization: After the process has been explicitly defined, present it to everyone. If you took the time to define the best practices for each activity, ensure that everyone who performs those activities knows the best way to do it. Provide training if necessary. Most importantly: ask for feedback!
-
Activity naming: Choose a name based on the most emblematic step.
Avoid unnecessary connectors or adjectives. Instead of “Develop the code and the automated tests,” go for “Develop code and tests.” Let the details (the tests are automated) be in the description.
Adopt the same style in all activities. The most popular ones are verb and objects (“Develop code”) and descriptive (“Developer writes code”). I’m more a fan of verb and objects, as it’s simpler and shorter. The space saved in the diagrams makes a lot of difference. - Definition of Done: Because of the lack of process documentation, I’ve seen many organizations trying to ensure that certain activities were executed by adding checks on the Definition of Done. This makes for a very convoluted DoD. After documenting the process, all you need is one item: Ensure process adherence. Your Definition of Done should focus much more on the deliverables than the activities necessary to build them. Refer to the Scrum Guide to see that the DoD is about WHAT needs to be done, not HOW: https://scrumguides.org/scrum-guide.html#commitment-definition-of-done.
It seems people don’t usually comment on stories on Medium. There are just a handful of comments, even in stories where I have thousands of readers and clapping. If you want to engage with other readers, exchange ideas, or provide feedback, sound off in the comments. It won’t go to waste; I’ll try to answer all of them. What has been your experience documenting processes?
Cheers!