Recently I visited DevOps Moscow. On the outside it may seem like an Alcoholics Anonymous club, but in fact it’s just DevOps engineers discussing their current issues:)
Most of the meeting we discussed the pain of working with documents. Sometimes there is nothing in it, sometimes it is outdated, then everything is in it, but you will find nothing. Discussed how to live with it
Headline
The conversation started with a situation where you already have the documentation, but you will not find anything in it and because of this no one uses it. How do you achieve this?
The idea of storing information has never been mentioned, you need to keep it where you will look for it. To understand where you are going to look, you need to write scenarios how users will approach the documentation for each of the tasks.
Every time someone couldn’t find something in the documentation, they had to convert this case into "problem + usage scenario". This will help you understand what’s wrong with the documentation now, since it is not used.
Headline
Headline
We need the engineer to quickly orient what where during the incident. You can, for example, write a page with a description of the project, a diagram, examples of what can be fixed, but most often during an incident no one will find and read this page. And that’s why we need scripts.
They explain how to help the engineer find a piece of documentation.
Scenarios in which the engineer understands that he has an incident and needs to do something: called the monitor, got an alert in Slack, looked at the chart in the monitoring and realized that something was wrong.
Since we have alert as the starting point of the script, let’s provide it with a reference to everything that man needs. In the background there may be references to documentation, service repository, dashboard in the county, last stock stock stock, etc. Do not need to look for anything, all at hand.
When the graph is the beginning of a scenario, you can do the same. To color out the areas that show that something is wrong, this will help the engineer at the moment of the accident not to think how to interpret the chart. Add to the description of each chart a description of what it shows why these values are bad, and a reference to the documentation describing what to do if this chart is bad.
Headline
Headline
The new person should have an idea of the project. Script: the person has just arrived and does not understand where to look.
Can introduce human through paired work with other engineer and not use documentation for onboarding.
Simulate the call! Great idea, I have never thought)) Make a chat with fairytales that will periodically arrive within a week.
And in the alleys there are already links to everything you need. While trying to respond to the alerts and check everything, the person will sort out the system and get acquainted with the documentation.
Headline
If the team is actively using documentation, this usually leads to people starting to update it regularly because they immediately notice its deviations from reality.
You can additionally push the team to update documentation as part of the process. For example, make this part of the Definition of Done of each task.
Make the update of directories, dashboards, documentation part of the process of closing the store. Run a script through the documentation to find pages that have not been updated for a long time, ask the team to update them.
In case when new people often appear in the team, you can give them a task to do something on the documentation, asking questions along the way and updating irrelevant places.
P.S. We were still discussing the problem of modular platform commands, but by this time I was tired and did not make notes :(
I advise on what I write, you can contact me by telegram or mail
