Working systems over comprehensive documentation
My last post described how your IT operations team can reap the benefits of a structured framework such as ITIL while recognizing opportunities for continuous improvement using the first Agile tenet: emphasizing individuals and interaction over processes and tools.
This concept is based on two supporting ideas: first, effective communication should be the primary focus of an IT operations team, and second, the processes and tools that your IT operations team uses, including the organizational framework, should be driven by the team’s needs rather than the desire to watchdog productivity.
This post looks at the second precept of the Agile Manifesto: Working software over comprehensive documentation.
Although software is integral to the work of a site operations team and some members of the team are often required to code as part of their daily activities, creating working software is not the primary function of an IT operations team, so we’re going to modify this precept to reflect the core competency of IT operations: Working systems over comprehensive documentation.
A common statement in the Agile community is “the left over the right,” meaning that in each Agile tenet, both halves are important, but the focus is on the first half. When applied to “working systems over comprehensive documentation” this means our focus as IT operations teams should be on maintaining working systems.
Maintaining working systems is the core competency of any IT operations team, and there is a lot of information available on how to do just that, so I’m not going to dig into it here. Keep in mind that, although the left is more important than the right from an Agile viewpoint, the right is important, too. It just has to be kept in perspective against higher priorities.
As a result, I’m going to examine how to add documentation to the regular activities of an IT operations team. It’s rare to have the luxury to build systems and documentation together from the ground up, and IT operations teams commonly feel understaffed. Often, they feel that they are scrambling just to have working systems in place, much less finding time to document them. When deciding between the two, working systems should take precedence every time.
If you want to provoke a negative emotional response in your IT operations team, tell them to spend more time on documentation. Documentation isn’t fun. It’s hard to know how to begin assembling it. Documentation takes away from the time your team can devote to deploying, fixing and maintaining systems. It’s not typically the strongest skill in an IT professional’s toolkit.
On the other hand, meaningful documentation can save a significant amount of time when troubleshooting. It can foster knowledge transfer. It speeds the learning curve for new hires trying to find their way around your systems. Documentation can be integral to a good disaster recovery plan.
Given the advantages and drawbacks to documenting your systems, how can you find a reasonable approach to creating the documentation?
The primary difference in the Agile approach to documentation lies in understanding the distinction between comprehensive documentation and meaningful documentation. Meaningful documentation supports your team’s needs.
Lay the groundwork for creating a culture that embraces documentation by discussing how your team would use different types of information. What drivers make documentation valuable to your team? As a group, determine what you need to document and why. This will generally come down to four key ways the knowledge will be used:
- Reduce troubleshooting time
- Share knowledge
- Support disaster recovery
If your team members recognize the value and purpose of documentation, not just as a general philosophy but as a meaningful tool supporting their daily activities, the team itself will start driving the effort to create and maintain documentation.
Document as You Go
It’s not practical to drop the regular work of an IT operations department and go on a documentation spree for a week. For one thing, everyone would take the week off. For another, knowing where to start documenting is a daunting proposition.
Instead, document as you go. Refer back to the ways your group will use the documentation as a guideline to creating it. For example, when a team member is working on a standard tasks – deploying, fixing, maintaining – use the opportunity to look at the system from a documentation standpoint as part of that task. If the team member were to hand off those tasks to a new colleague, what would that colleague need to know to get those tasks done?
Reduce troubleshooting time
One way to create documentation is to embrace failure. When your systems fail, use the opportunity to strengthen them, address the root causes, and document both the fix and the new, stable state. This can support future troubleshooting efforts while creating training material.
The intricacy of modern IT operations means that individuals are forced to specialize. Your team members can’t be experts on every aspect of your systems. This means that even senior, well-established team members will have to ping colleagues for answers about systems as part of their regular work. If you have meaningful, readily available documentation that is easy to access, team members will interrupt each other less often, leading to greater productivity across the team.
Understanding the complexities of an organization’s systems can be the longest pole in getting a new team member up to speed and performing. If that organization can supply new team members with meaningful documentation, velocity increases for that team member and the number of interruptions fielded by existing team members from questions the new team member might ask will drop.
Expanding on that thought, use the opportunity of onboarding new hires to create the documentation that is missing. As new team members are taught the system by their more experienced colleagues, they can document the information they are taught and then have it reviewed by the person teaching them.
Support disaster recovery
Disaster recovery generally requires the most detailed, comprehensive documentation. This falls outside the “document as you go” method, requiring a dedicated project and maintenance plan to be effective. However, if you have meaningful documentation in place, it can provide a springboard into the disaster recovery plan.
Understanding how documentation can support your IT operation team’s needs guides team members in creating and maintaining documentation that is meaningful to the team.
In part 3 of this series I will examine how the third precept of the Agile Manifesto, customer collaboration over contract negotiation, can be implemented an IT operations environment.
Jen Stone Browne