In this article, we take a look at the benefits of operation manuals to an organization, and how to go about creating a great one.
Join the DZone community and get the full member experience.Join For Free
[Latest Guide] Ship faster because you know more, not because you are rushing. Get actionable insights from 7 million commits and 85,000+ software engineers, to increase your team's velocity. Brought to you in partnership with GitPrime.
Yeah, yeah, this sounds boring. And in reality, it is. Until you realize how much time and money operation manuals save you. Let's ise a small example with numbers in it. Obviously, I have just made this up, but you can get the idea. Imagine you are responsible for training a new team member. Now, the new person comes in, let’s call him Peter. So you sit down with Peter and explain to him everything about the team, how to set up the environment, how to submit the work, and many other things. Then you go back and forth with questions. So in total, you might spend a good 5 hours with him. Now imagine that you have prepared a quick starter manual for him. Peter does his homework and comes up with questions after. If the manual is good enough, then the time you spend with him can be shorter than 1 hour. That's a 4-hour difference! If you need to do the same training 5 times, then the difference is 20 hours of YOUR time. You can make long lunches, get extra sleep, or spend that time with people you love. And of course, training is just one particular usage. I am personally using operation manuals in many cases and they save me literally hundreds of hours every year. And you can do the same.
Note: Operation manuals are a framework which allows you to outsource activity to other people.
Now, when you understand what operation manuals can do for you, let's look on how to create them and then how to use them.
Good news for creation. At first, this is mostly just a one-time action. Once you go through this process, then you are basically done and you will be able to benefit from it for years. The second bit of good new is that I have prepared templates for you. They are in the Appendix. Please feel free to start with them. And finally, the third piece of good news. There is no need for any special tool. At the beginning start with a text editor. It's enough. First, create the content and I will tell you later where to put it.
The whole creation process has 2 steps: role identification and content writing. Role identification is an important 5-minute exercise. Take a pen and some paper and draw the diagram with the structure of your team. Here is an example:
This particular example usually works well for a small software team of 3-10 people. However, the system itself is independent of team size and will scale even to the big teams. In this example business analyst prepares the work, the designer puts a nice face behind it, the developers makes it work, the tester ensures that developer did the right job, and the environment manager releases it. Everything is under your supervision as a project manager. Don't worry if you don't have people for certain roles, if someone does work in multiple roles, or if multiple people work in the same role. All these situations are normal in the real world. This diagram is just a logical separation of your team into roles. I have personally changed all of these roles and even now I am sometimes wearing these hats. Also, you don't need to be perfect the first time. Produce something and optimize later.
Now when you have the roles it is time to start with content writing. This is where the majority of effort happens. Start from the bottom of the tree. Pick up one role and write a detailed job description. If you have a team, then go and talk to the people to discover what they are actually doing. If you don't have a team, then just imagine what they would be doing. Again, no perfection is needed on the firstgo around.
Tip: Start your writing with an outline and then step by step fill in the blank spaces. And have a look at the Appendix for templates.
Once you are done, then go to the next role on the same level and keep going. When all the roles are done on the lowest level, then move up in the tree. At the end, you will write the manual for the top level positions, which is typically your own work. Finally, it is good practice to create one extra manual called a Welcome manual. The welcome manual acts as a starting point for every new member. It can be very short. Just a simple introduction and reference to the other manuals. That's all. When you finish with this, then take a breath. You have just created a lifetime asset for yourself.
Note: In the ideal case, manuals would have all you want from every team member. Experience tells me that 100% accuracy is impossible. What is possible is to be 90% accurate. This is good enough.
There is one more thing to mention. And this is the maintenance of operation manuals. As you can imagine, nothing is static and even operations manual needs to stay up to date. There is not really a hard rule for when to make updates. For some organizations, a periodic review might be the right choice. For others, a review based on events might be better. I personally prefer the latter. In the chapter about processes, I will give you an example of a time when it is good to do that.
It is a lot of documents. I understand how much effort you have to put in to produce something useful. I did the same work on my own. Therefore, you might be asking how to use them. To give you an answer, I have prepared use cases from real life. And over the time as you create better and better manuals the new use cases will naturally appear.
Before you hire anybody, there must be work for that person to do. And that is the value you will bring the operation manual. A description of the work is done. So with a little extra effort, you can have everything you need to present to recruiters. Sooner or later some reasonable candidate will appear and you decide to proceed with and interview. As a part of the interview, give him/her a small task to see whether they are capable of finishing the work according to your standards. You will be surprised how many candidates will be eliminated because they are either not able to finish the task or the work is done in the wrong way. And this is good because you don't need to waste time with people who will break the team. And even better, this type of measurement will allow you to evaluate the performance regardless of age, gender, race, or whatever. The only thing that matters is the result. After the first interview focus only on the people who pass. During the next stage, make sure you ask them in a crystal clear way whether they are willing to follow these manuals. I have been doing this for a couple of years and the only answer I have ever heard was 'yes.' And this is the gentleman's deal which will save a lot of future headaches for both of you.
Imagine you have a new team member. In many companies, a more senior person is asked to educate the newbie. And now imagine how much time this costs, especially if the same talks have to be given again and again. There is a more efficient way. Let people read the relevant operation manuals first. Then they will be allowed to ask questions. And even better, while answering these questions, take notes. Then update your manuals to be even more efficient the next time.
Imagine you have a little project which can be done by freelancers. If you just post your project to some of the freelancer pages, then the result will most likely be of poor quality. It actually makes sense. You don't want to spend money on freelancers and freelancers just want to get paid for your project as soon as possible and move on. If you want to keep the quality, then operation manuals are the right choice. You have to write down what your quality standard is. Then submit this manual together with a project description and make sure that following the manual is a **must** condition to release the payment. This way you will get the result you want at a good price.
Management and Evaluation
Compare what you have written in the operation manuals with what people actually do. Do you see anyone who is doing the work described in the most of the operation manuals? If yes, then this is great. This person is a candidate for promotion, maybe even to become one of the main leaders (CTO, director, etc.). Good leaders are capable of doing most of the work on their own. On the other side, you might be able to see someone who is struggling to do the described work. There might be two reasons for this. First, the operation manuals are of a bad quality. You can discover this case typically by letting several people follow that particular manual. If more of them are struggling, then you know this is most likely problem in the manual. In such a case, it is your responsibility to improve the quality. The second reason is that the person is underperforming. This is when other people have no problem following the manual. Now the task is to discover the reason for underperformance. This might have many different causes, starting from personal issues, the wrong choice of work, not enough education, or just slacking. In any case, your work in such cases is to figure this out and do something.
It is always hard when someone good leaves the team. Unfortunately, in many instances, this is out of the manager's control. What a manager can do is to prepare for when this happens. It is like a tsunami. You can't stop them from happening, but you can build walls to protect the houses. If operation manuals are written well, then intellectual property stays in-house. And as you could read before, operation manuals will help to find a replacement as well.
Tasks like product release, troubleshooting, or periodic checkups are great examples. They are usually performed only once in while. And usually, they are just a big list of instructions. Nobody can ever remember them. Therefore operation manuals are a good place to store them.
- Create some operation manuals as soon as possible.
- Use operation manuals for outsourcing the work to other people.
- Keep improving them.
Welcome Manual (Template)
Third parties (e.g. cloud or service providers).
Disclose what information is tracked.
Special events (e.g. releases).
Reference to other operation manuals
Business Analyst Operation Manual (Template)
Where to put the documents.
How to break a feature into small steps.
How to write requirements.
Rules for including external links into specifications.
Writing a test plan:
What features needs test plan.
Where to create test plan.
.How to write test plan
Designer Operation Manual (template)
What we use.
Not allowed customizations.
Developer Operation Manual (Template)
How to prepare your environment:
Automatic code formatter.
Set up for a local run.
Commit message policy.
Time tracking through smart commits.
Tester Manager Operation Manual (Template)
Who the test coordinator is.
Where to find test cases to do.
When the testing phase starts.
Access to the test environment.
How to start test planning.
How to execute test cases.
How to report bugs.
Situations which cause the test to stop.
How to report the overall outcome.
Random walk tests:
When to execute.
How to report a bug.
Environment Manager Operation Manual (Template)
Project management environment:
Passwords for those without sensitive information.
Certificate renewal procedure.
Troubleshooting (list all problems you had and how to solve them)
Opinions expressed by DZone contributors are their own.