In This Article

Plans are worthless, but planning is everything. 

-- Dwight D. Eisenhower, Wikiquote.org


XP is designed to use face to face human communication in place of written documentation wherever possible. Effective conversation is faster and more effective than written documentation. When you bring people together, they need less paperwork.

-- "Essential XP: Documentation" by Ron Jeffries


Regular, even constant, collaboration is a hallmark of agile software development. The first two of the four values of the Manifesto for Agile Software Development assert "individuals and interactions over processes and tools" followed by "working software over comprehensive documentation." Yet does this still apply in a world where we all work from home? 

Yes, we can Webex or Slack, but no matter how great the tools, an additional bit of friction still gets in the way of the type of interaction required by a high-performing agile software development team. Maybe we need to think differently?

copy link

A not so agile situation

Imagine a scenario where a developer launches her browser-based work board and opens a ticket. Let's assume that said developer works for an agile software development shop, and this ticket is a user story. The developer reads the user story and sort of gets what it's about but has questions. The developer shakes her head and thinks, "just a few months ago I'd walk over to my product owner or a teammate and talk it over. Now, we're all working from home and it's such a pain to get a simple question answered. I think I'll just send an email and go get some coffee while I wait." 

Now imagine this scenario playing out thousands upon thousands of times an hour around the globe. Might this waste be avoided through more upfront documentation? Would it be a tragic loss to make a user story more explicit and less of an invitation to a conversation?

Since the early days of Agile software development, a tension has existed between those who desire more up-front documentation for a solution and "pure" agilists regarding what and how much to document. Someone steeped in Extreme Programming (XP) might argue that clearly written code, commit logs and test cases are all you need. A PMI trained project manager might shake his or her head and patiently explain we need a PRD (product requirements document) and SRD (software requirements document) in order to create an acceptable WBS (work breakdown structure). 

In most situations in the world of agile, this dialectic resolves into some middle ground. Some upfront documentation gets written, along with light-to-medium-weight user stories, with the intent that the unspecified parts of the stories can be resolved through conversation. 

"Weeks of programming can save you hours of planning."

-- Unknown (get the T-Shirt!)

The above quote generally draws a good chuckle from anyone involved in the craft of software development. Even those who know the beauty of great agile collaboration can understand that we don't want to be so strict in our approach as to slip into a "ready-fire-aim" paradigm. We want some degree of rigor around how we think through a solution prior to putting hands to keyboard. 

What if the remoteness forced upon us by a crown-shaped piece of chemistry could actually become a forcing-function for such rigor? What if the lack of face-to-face communication becomes an advantage for those who take an intentional approach to collaboration via some up-front documentation? 

copy link

How collaboration becomes agile

Consider this statement: "individuals and interactions and processes and tools where it makes sense." This "yes, and" approach implies the agile inclination towards communication through conversation can coexist in juxtaposition with written documentation. We now have tools that allow for a synchronous, real-time experience to collaborative creation and editing. 

We no longer need to email Visio attachments of UML diagrams or Word documents. We have tools like Lucidchart, Google Docs or Confluence at our disposal, just to name a few. Even Microsoft Office has reinvented itself as a collaboration suite. 

Combined with individual and group chat and video calls, it's relatively simple to align on the intent and high-level implementation of a solution. Yes, these tools introduce more friction than swiveling your chair to ask a question, but you get the benefit of an artifact that expresses a clear and aligned understanding. That seems like a net benefit.

In our distributed world, the ability to work independently and collaboratively on the same artifact becomes an advantage. We can take the time to think through a problem individually and apply the output in a focused way when working alone. Others do the same. We come together when needed to talk through our thoughts and to improve, refine and align.

This is all well and good, yet what prevents us from spending many hours creating artifacts that may obsolesce as we develop our software? Perhaps we might benefit from some simple litmus tests. As you collaborate on your artifact, regularly ask yourself, "do I know enough to start coding with a degree of confidence it'll deliver value to my end-user?" 

If yes, then check in with the appropriate people to confirm your assumption while getting ready to code. "If I delete the bit I just wrote, would it significantly alter the software we're about to write?" If not, then delete it and stop documenting. "Is it getting more-and-more difficult to express my thoughts in writing?" Maybe you're getting into the weeds. "How long has it been since I got feedback from a teammate?" If it's more than a couple of hours, perhaps stop and get that cup of coffee in preparation for a conversation.

"In writing, you must kill all your darlings."

-- William Faulkner

You want to make sure the artifacts you create are accessible, meaningful, contextual, small and modular. This applies whether using plain language, a data model, an object model, a sequence diagram or anything else like that. Small documentation, like small code, is more likely to add just enough value and be more maintainable as a living artifact. 

Just as with code, you want to try not to become attached to what you've written. Pay attention to the modular piece in particular. Modular documentation can be more easily re-purposed. It's also more discoverable and yields faster answers to the finder.

copy link

Where to start

There is a range to the quality and suitability of the tools you may choose to collaboratively create and maintain your artifacts. Spend some time to evaluate your choices. Try before buying whenever possible. Once you start to use a tool, you can think about the degree of fearlessness you have when making a change to someone else's work; your fear may come from a lack of trust or it might be a lack of good version control and notifications. 

You want to consider having an agile collaboration retrospective. Get together on a video call to discuss how well your current collaboration stack and approach meets your needs. After all, there's no substitute for a good face-to-face conversation, even if only on video. Just be sure to document the meaningful results.

Learn more about our software expertise.