What does Agile documentation look like?

Reading through Dusty Phillips’ second edition of “Python 3 Object-oriented Programming,” this quote caught my attention:

Further, the most important person you will ever have to communicate with is yourself. We all think we can remember the design decisions we’ve made, but there will always be the Why did I do that? moments hiding in our future. If we keep the scraps of papers we did our initial diagramming on when we started a design, we’ll eventually find them a useful reference.

That strikes me as a good benchmark for acceptable documentation in Agile. Whether coder, UI/UX designer, data architect, or whatever, if you are keeping a good record of what you decided and why, you’ll probably be able to recreate the rationale for why things got to be the way they are for anybody who needs to know. Especially if that anybody is you. And there is a good chance that someone following in your footsteps will be able to pick up the same rationale even in your absence. All this without putting an unnecessary burden on project progress for the sake of detailed documentation.

Of course, what qualifies as “good” is the tricky part. A suggested threshold would be to specify only as much information as makes sense or for what is known given the current situation. Documentation should be subject to iterative practices just as much as code.

False Barriers to Implementing Scrum – II

In a previous post, I described several barriers to implementing scrum. Recently, an additional example came to light similar to the mistake of elevating scrum or Agile to a philosophy.

In a conversation with a colleague, we were exploring ways on how we might drive interest for browsing the growing wealth of Agile related information being added to the company wiki.  It’s an impressive collection of experiences of how other teams have solved a wide array of interesting problems using Agile principles and practices. Knowing that we cannot personally attend to every need on every project team, we were talking through various ways to develop the capacity for exploration and self-education. I think I must have used the phrase “the information is out there and readily available” a couple of times to many because my colleague reacted to where I put the bar by comparing learning Agile to surgery.

Using the surgery metaphor, she pressed the comparison that all the information she needs about surgery is “out there and readily available” but even if she knew all that information she likely wouldn’t be a good surgeon. Fair point that experience and practice are important. And if that is the case, then everyone should be taking every opportunity they can to practice good agile rather than regressing to old habits.

More importantly, perhaps, is the misapplied metaphor. Practicing agile isn’t as complicated as surgery or rocket science or any other such endeavor that requires years of deep study and practice. Comparing it to something like that places the prospects of doing well in a short amount of time mentally beyond the reach of any potential practitioners.

Perhaps a better metaphor is the opening of a new rail line in the city. A good measure of effort needs to be expended to educate the public on the line’s availability, the schedules, how to purchase fares, where the connections are, what are the safety features, etc. Having done that, having “put the information out there where it is generally available,” it is a reasonable expectation that the public will make the effort to find it when they need it. It is unreasonable, and unscaleable, to build such a system and then expect that every passenger will be personally escorted from their front door to their seat on the train.

It is also interesting to consider what this does to the “empathy scale” when such an overextended metaphor is applied to efforts such as learning to practice Agile. If we frame learning Agile as similar to surgery then as people work to implement Agile are we more inclined to have an excessive amount of empathy for their struggles and be more accepting or accommodating of their short comings?

“Not to worry that you still don’t have a well formed product backlog. This is like surgery, after all.”

Are we as an organization and each of our employees better served by the application of a more appropriate metaphor, one that matches the skill and expectations of the task?

“We’ve provided instruction as to what a product backlog is and how to create one. We’ve guided you as you’ve practiced refining a product backlog. You know where to find suggestions for improving your skills for product backlog stewardship (wiki, books, colleagues, etc). Now role up your sleeves and do the work.”

Successful coaching for developing the ability in team members for actively seeking answers requires skillfully letting them struggle and fail in recoverable ways. It is possible to hold their hand too long. To use another metaphor, provide whatever guidance and instruction you need to so they know how to fish, then let them alone to practice casting their own line.

Photo credit: langll

How to know when Agile is working

On a recent flight into Houston, my plane was diverted to Austin due to weather. Before we could land at Austin, we were re-diverted back to Houston. I’ve no idea why the gears aligned this way, but this meant we were out-of-sequence with the baggage handling system and our luggage didn’t arrive at the claim carousel for close to an hour and a half. Leading up to the luggage arrival was an unfortunate display from an increasingly agitated young couple. They were loudly communicating their frustration to an airport employee with unknown authority. Their frustration was understandable in light of the fact that flights were undoubtedly going to be missed.

At one point, the woman exclaimed, “This isn’t how this is supposed to work!”

I matched this with a similar comment from one of the developers on one of my project teams. Stressed with the workload he had committed to, he declared there are too many meetings and therefore “the agile process is not working!” When explored, it turned out some version of this sentiment was common among the software development staff.

In both cases, the process was working. It just wasn’t working as desired or expected based on past experience. In both cases, present events were immune to expectations. The fact that our luggage almost always shows up on time and that agile frequently goes smoothly belies how susceptible the two processes actually are to unknown variables that can disrupt the usual flow of events.

There is a difference with agile, however. When practiced well, it adapts to the vagaries of human experience. We expect the unexpected, even if we don’t know what form that may take.

There is an assumption being made by the developers in that “working agile” makes work easy and stress free. I’ve never found that. And I don’t know anyone who has. It stresses teams differently than waterfall. I’ve experienced high stress developing code under both agile and waterfall. With agile, however, teams have a better shot at deciding for themselves the stress they want to take on. But there will be stress. Unstressed coders deliver code of questionable value and quality, if they deliver at all.

The more accurate assessment to make here is that the developers aren’t practicing agile as well as they could. That’s fundamentally different from “agile isn’t working.” In particular, the developers didn’t understand what they had committed to. Every single sprint planning session I’ve run (and the way I coach them to be run) begins with challenging the team members to think about things that may impact the work they will commit to in the next sprint – vacations, family obligations, doctor visits, other projects, stubbed toes, alien abductions – anything that may limit the effort they can commit to. What occurred with the developers was a failure to take responsibility for their actions and decisions, a measure of dishonesty (albeit unintended) to themselves and their team mates by saying “yes” to work and later wishing “no.”

Underlying this insight into developer workload may be something much more unsettling. If anyone on your team has committed to more than they can complete and has done so for a number of sprints, your project may be at risk. The safe assumption would be that the project has a hidden fragility that will surprise you when it breaks. Project time lines, deliverables, and quality will suffer not solely because there are too many meetings, but because the team does not have a good understanding of what they need to complete and what they can commit to. What is the potential impact on other projects (internal and client) knowing that one or more of the team members is over committing? What delays, quality issues, or major pivots are looming out there ready to cause significant disruptions?

The resolution to this issue requires time and the following actions:

  • Coaching for creating and refining story cards
  • Coaching for understanding how to estimate work efforts (points and/or time)
  • Develop skills in the development staff for recognizing card dependencies
  • Develop skills for time management
  • Find ways to modify the work environment such that it is easier for developers to focus on work for extended periods of time
  • Evaluate the meeting load to determine if there are extraneous meetings
  • Based on metrics, specifically limit each developer’s work commitment for several sprints such that it falls within their ability to complete

Image credit: Prawny

False Barriers to Implementing Scrum

When my experience with scrum began to transition from developer to scrum master and on to mentor and coach, early frustrations could have been summed up in the phrase, “Why can’t people just follow a simple framework?” The passage of time and considerable experience has greatly informed my understanding of what may inhibit or prevent intelligent and capable people from picking up and applying a straightforward framework like scrum.

At the top of this list of insights has to be the tendency of practitioners to place elaborate decorations around their understanding of scrum. In doing so, they make scrum practices less accessible. The framework itself can make this a challenge. Early on, while serving in the role of mentor, I would introduce scrum with an almost clinical textbook approach: define the terms, describe the process, and show the obligatory recursive work flow diagrams. In short order, I’d be treading water (barely) in endlessly circuitous debates on topics like the differences between epics and stories. I wrote about this phenomenon in a previous post as it relates to story points. So how can we avoid being captured by Parkinson’s law of triviality and other cognitive traps?

Words Matter

I discovered that the word “epic” brought forth fatigue inducing memories of Homer’s Iliad and Odyssey, the Epic of Gilgamesh, and Shakespeare. Instant block. Solution out of reach. It was like putting a priceless, gold-plated, antique picture frame around the picture postcard of a jackalope your cousin Eddie sent you on his way through Wyoming. Supertanker loads of precious time were wasted in endless debates about whether or not something was an epic or a story. So, no more talk of epics. I started calling them “story categories.” Or “chapters.” Or “story bundles.” Whatever it took to get teams onto the idea that “epics” are just one of the dimensions to a story map or product backlog that helps the product owner and agile delivery team keep a sense of overall project scope. Story writing progress accelerated and teams were doing a decent job of creating “epics” without knowing they had done so. Fine tuning their understanding and use of formal scrum epics came later and with much greater ease.

“Sprint” is another unfortunate word in formal scrum. With few exceptions, the people that have been on my numerous scrum teams haven’t sprinted anywhere in decades. Sprinting is something one watches televised from some far away place every four years. Maybe. Given its fundamental tenets and principles, who’s to say a team can’t find a word for the concept of a “sprint” that makes sense to them. The salient rule, it would seem, is that whatever word they choose, the team fully understand that “it” is a time-boxed commitment for completing a defined set of work tasks. And if “tide,” “phase,” or “iteration” gets the team successfully through a project using scrum than who am I to wear a the badge of “Language Police?”

A good coach meets the novice at their level and then builds their expertise over time, structured in a way that matches and challenges the learner’s capacity to learn. I recall from my early Aikido practice the marked difference between instructors who stressed using the correct Japanese name for a technique over those that focused more on learning the physical techniques and described them in a language I could understand. Once I’d learned the physical patterns the verbal names came much more easily.

Full disclosure: this is not as easy when there are multiple scrum teams in the same organization that eventually rotate team members. Similarly, integrating new hires with scrum experience is much easier when the language is shared. But to start, if the block to familiarization with the scrum process revolves around semantic debates it makes sense to adapt the words so that the team can adopt the process then evolve the words to match more closely those reflected in the scrum framework.

Philosophy, System, Mindset, or Process

A similar fate awaited team members that had latched onto the idea that scrum or agile in general is a philosophy. I watched something similar happen in the late 1980’s when the tools and techniques of total quality management evolved into monolithic world views and corporate religions. More recently, I’ve attended meet-ups where conversations about “What is Agile?” include describing the scrum master as “therapist” or “spiritual guide.” Yikes! That’s some pretty significant mission creep.

I’m certain fields like philosophy and psychotherapy could benefit from many of the principles and practices found in agile. But it would be a significant category error to place agile at the same level as those fields of study. If you think tasking an agile novice with writing an “epic” is daunting, try telling them they will need to study and fully understand the “philosophy of agile” before they become good agile practitioners.

The issue is that it puts the idea of practicing agile essentially out of reach for the new practitioner or business leader thinking about adopting agile. The furthest up this scale I’m willing to push agile is that it is a mindset. An adaptive way of thinking about how work gets done. From this frame I can leverage a wide variety of common, real-life experiences that will help those new to agile understand how it can help them succeed in their work life.

Out in the wild, best to work the system and process angles if you want meaningful work to actually get done.

Parkinson’s Law of Triviality and Story Sizing

From  Infogalactic: Parkinson’s law of triviality

Parkinson observed and illustrated that a committee whose job was to approve plans for a nuclear power plant spent the majority of its time on discussions about relatively trivial and unimportant but easy-to-grasp issues, such as what materials to use for the staff bike-shed, while neglecting the non-trivial proposed design of the nuclear power plant itself, which is far more important but also a far more difficult and complex task to criticise constructively.

I see this phenomenon in play during team story sizing exercises in the following scenarios.

  1. In the context of the story being sized, the relative expertise of each of the team members is close to equal in terms of experience and depth of knowledge. The assumption is that if everyone on the team is equally qualified to estimate the effort and complexity of a particular story then the estimation process should move along quickly. With a skilled team, this does, indeed, occur. If it is a newly formed team or if the team is new to agile principles and practices, Parkinson’s Law of Triviality can come into play as the effort quickly gets lost in the weeds.
  2. In the context of the story being sized, the relative expertise of the team members is not near parity and yet each of the individual team members has a great deal of expertise in the context of their respective functional areas. What I’ve observed happening is that the team members least qualified to evaluate the particular story feel the need to assert their expertise and express an opinion. I recall an instance where a software developer estimated it would take 8 hours of coding work to place a “Print This” button on a particular screen. The credentialed learning strategist (who asked for the print button and has no coding experience) seemed incredulous that such an effort would require so much time. A lengthy and unproductive argument ensued.

To prevent this I focus my coaching efforts primarily on the product owner as they will be interacting with the team on this effort during product backlog refinement session more frequently than I. They need to watch for:

  1. Strong emotional response by team members when a size or time estimate is proposed.
  2. Conversations that drop further and further into design details.
  3. Conversations that begin to explore multiple “what if” scenarios.

The point isn’t to prevent each of these behaviors from occurring. Rather manage them. If there is a strong emotional response, quickly get to the “why” behind that response. Does the team member have a legitimate objection or does their response lack foundation?

Every team meeting is an opportunity to clarify the bigger picture for the team so a little bit of conversation around design and risks is a good thing. It’s important to time box those conversations and agree to take the conversation off-line from the backlog refinement session.

When coaching the team, I focus primarily on the skills needed to effectively size an effort. Within this context I can also address the issue of relative expertise and how to leverage and value the opinions expressed by team member who may not entirely understand the skill needed to complete a particular story.

(John Cook cites another interesting example of Parkinson’s Law of Triviality (a.k.a. the bike shed principle) from Michael Beirut’s book How to involving the design of several logos.)

Showcasing Innovative Adaptations of Agile

Working Agreements

“Our working agreements had become a little cumbersome,” remarked Joseph, the PO for the Crain, Schmidt, and Poole account. “In fact, they were so bad we considered just adopting the Microsoft Windows End User License as an abbreviated version of our working agreements.”

“It was pretty ridiculous,” added Sonya, a software developer on the project. “Our first retrospective took eleven weeks to complete, mostly due to the delays caused by everyone’s lawyers working out the language around things that needed improvement. We all seemed pretty OK with taking responsibility for our own work but were adamant that someone else should be held accountable for the problems we were facing.”

“In the end we all agreed that Chester, the testing goat, should be the one held accountable. Dual use: testing goat and scapegoat. Seemed pretty efficient to us,” said Denny, the team’s tQA expert.

“And that’s where it all started. Our drive for greater efficiencies, I mean,” said Bernie, a second developer on the project. “Rather quickly, we were collapsing all sorts of two’s and three’s into one. Before long, our 342 page working agreements document was down to three sentences. The PO was thrilled to drop the attorneys from the project budget.”

“Yeah,” added Denny. “Even Chester is back to being just a plain ol’ testing goat again.”


“Nobody says anything in stand-ups. Zip. Zero. Nada. Nothing.” proclaimed Kurt, scrum master for the Cleo Parker Robinson account. “It’s a room full of clinically certifiable introverts,” declared Seth, the project’s product owner. “They make Marcel Marceau seem annoyingly chatty by comparison,” he added. “Turns out, that was just us being blinded by our own biases and assumptions. One day, Tracy, one of the senior developers on the project all of the sudden slapped both her palms on the conference table, grabbed the polycomm, and started swinging it like a pendulum. Then Raj jumped up, put one hand over his left ear and stretched his right arm out straight. Then Truman made a noise that sounded something like ‘Ahhhhyooooye!’ and started pantomiming like he’s dealing cards. After that, all manner of odd behavior unfolded before our eyes.”

“By the end of the day,” Kurt added, “the number of cards for the sprint in the ‘Done’ column went from 20% to just over 80% – and there’s four days left in the sprint!”

“That’s when it struck us,” interrupted Seth. “The agile delivery team had been paying VERY close attention during the subject matter expert’s all day intensive discovery sessions from the design study. They were communicating their stand-ups through interpretative dance! From then on, it was easy. We just had to work to stay out of their way.”

Sprint Reviews

“We’d just kicked off the project with the Gucci account and muddled through our first working session, but it just didn’t feel productive,” said Carmine, a UI/UX expert. “Something was preventing us for actually getting to work. It was like we were pretending or something,” she added.

“So we hit on the idea we weren’t dressed for the part. We brainstormed a zillion outfit options and ran through an affinity exercise on the results before deciding on the optimal wardrobe,” chimed in Zeke, a tQA specialist.

“I have to admit, though,” shared Carmine. “It was a pretty awkward moment at the start of our first review with the client. There we were, sitting across the table from what must have been a million bucks worth of gabardine and silk and us in our flannel shirts, bib overalls, and work boots. Luckily, our PO is brilliant. She reached out, put her hand on the CLO’s shoulder and said, ‘Don’t worry. They’re Carharts!’ Huge sighs of relief filled the conference room knowing only quality name brands were present. We rolled up our sleeves and they loosened their ties and shirt collars and we stepped through a fantastic demonstration.”

The Future of Scrum

“Form a hypothesis, design an experiment, and then analyze the results. That’s really all we do,” said Guy Torqué, Senior Research Associate at the Institute for Advance Agile Research in Marseille, France. “We don’t always get it right. For example, we hypothesized that if standing up during meetings prompted participants to move through meetings more efficiently then perhaps if we had them stand on their heads the efficiency would increase even more. What we discovered is that people just passed out and meeting recovery time increased substantially. Similar results happened with our tests using advanced yoga poses.”

But that didn’t stop the intrepid researchers from pressing forward. They also experimented with having participants lighting and holding onto a match when it was their turn to speak during stand-ups. This did increase the speed at which individuals moved through the classic three questions for stand-ups, but unfortunately it also decreased productivity as agile delivery team members were less motivated to develop work products with burned fingers.

“Agile team role development is another area of acute research interest,” said Guy. “We’re currently testing a ‘Product Owner of Fortune’ hypothesis. Several weeks ago we dropped a dozen highly trained product owners deep into the interior of several politically unstable countries with a satchel full of sticky notes and marker pens. Our hypothesis is that they should be able to successfully define a set of minimum viable procedures that will successfully lead them out of the troubled areas. We haven’t heard back from any of them as yet. But it’s early,” he said, optimistically.

More Resources for the Curious