Document Based

If the model of an organization’s software delivery is the code of that org, what follows is the documentation. It’s what new members can pick up on the first day, read in one sitting, and grok the mechanics of your organization. Just like the model, it’s subject to change as the organization changes, but like the model, it’s important to have it explicitly stated because it acts as a starting point for recursive self-improvement.

Your Own “Scrum Guide”

No two organizations of the same. No two organizations will have the same values, roles, workflow, or personalities. Why then do we try to apply generic documents to widely diverse groups in such a way that ignores or disregards their distinct characteristics? Creating your own agility handbook provides an opportunity to capture in natural language how your organization works, the number and function of the different roles, and how different entities relate and interact to produce value. It also acts as a critical change agent because as the organization changes those changes make their way back into the agility handbook which then gets repropagated throughout the organization.

A great leader demonstrating this value is GitLab. Read about their handbook-first approach to documentation here

The UPMC Case Study

At the beginning of the 2020 global pandemic, the MyUPMC software group of UPMC faced a trifecta of sudden change:

  1. Everyone in the department was sent home. This meant rethinking our communication and collaboration methods. The increased digital communication increased the possibility of communication overhead overload.
  2. A freshly approved new budget meant that the program would be doubling in size. That meant onboarding people and organizing teams without seeing each other face-to-face or interacting through typical conversation. This doubling in size meant that a more planned out and comprehensive onboarding strategy and orientation would also be required.
  3. Lastly, there was a sudden spike of customer requests related to COVID-19 testing, which meant a succession of expedited production releases were on the table.

To summarize, the entire operation needed to move faster, grow, and change the standard way of working at the same time and in a very short period of time. For all of the above reasons, significant changes needed to happen in processes and procedures. In the past, we got by having some meetings and conversations and going for walks one-on-one with folks to socialize ideas and settle on changes over time, but that whole dynamic was going to be different now. Suddenly the need for a canonical written source of process and procedures became evident. We needed a masthead, a comprehensive truth source that unpacked our shared software delivery process at the program level. The result of trying to address this need was the publication of a program-wide “Agility Handbook”. 

The Agility Handbook

This new agility handbook addressed several needs:

  1. It’s specified changes we need to make across all teams to facilitate interoperability and alignment.
  2. It documented specific things that we were doing there were institutional knowledge that would have been lost if certain vital people left.
  3. It included both of these in a short but comprehensive document that could be used in two ways:
    1. As a central point of reference in discussion with existing team members
    2. Then doesn’t onboarding tool for new hires.

We invested a lot of mental effort on what to include, what not to include, and how to communicate it in the most concise way possible. We labored strenuously for simplicity. Now I have to admit when we released this document, I was one proud papa. My agility cohort, Rick Pollick, and I felt really good about the final product, so I did what anyone would do. I shared it with some old Scrum Master friends of mine, possibly looking for a little kudos. One response stuck out to me more than the others, and it was this: “Why not just use the scrum guide?”

Every organization’s software delivery process is going to be inevitably unique. It’s important that that process is documented and codified in such a way that various teams independently and yet compatibly. 

See our case studies page for a detailed breakdown of this work.


Reasons to write your own Agility Handbook

  1. If you deviate from any point from the Scrum Guide, you can’t use it as your manual [show chart]

Potential or common deviations:

  1. Pure kanban teams. They very likely won’t have the same ceremonies as a team that’s sprinting.
  2. Component teams that provide critical infrastructure requirements to your feature teams and don’t produce vertical slice features as their primary deliverables.

These exceptions are not outliers in fact, they are the vast majority of the norm as it’s been documented that most teams you said mixed methods approach [show chart].

  1. The Scrum Guide is not specific to your organization.

There will be specific implementation details and pain points specific to your org’s application of scrum. Possible examples could be…

  1. Release planning (Nexus?)
  2. Workflows (Kanban)
  3. Component teams and tribes (SAFe influence)
  4. The Prime Directive (Values)

The Alternative

Now one possible alternative to doing this would be to have new folks read the Scrum Guide, Nexus, the Kanban guide for scrum teams, a few miscellaneous SAFe articles, and then some final material covering our specific implementation details that are either not covered by the previous works or contradicted by them. 

Two final thoughts before moving into our final section:

  • The MyUPMC Agiltu handbook is not yours.
  • Existing handbooks and manuals are great starting points and templates for your organization’s handbook.

Essential Characteristics

  1. Actionable: As useful as a map. Comprehensive enough to be useful in onboarding.
  2. Concise: Short enough to read in one sitting (Concise with moderate commitment).
  3. Living + dynamic: In Source control, anyone can make a pull request and everyone can subscribe to changes. This produces a mechanism whereby the document evolves and changes through the natural review process and engineers are accustomed to.
  4. Endorsed: this means leadership is behind it and it’s put its stamp on it and presented it to the organization as the dynamic blueprint for its software process.