In This Article

Plans are worthless, but planning is everything. 

-- Dwight D. Eisenhower,


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 use Webex or Slack, but no matter how great the tools are, an extra 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.

A not-so-agile situation

Imagine a scenario where a developer launches her browser-based workboard 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 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 getting a simple question answered is a pain. 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, 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 written code, commit logs, and test cases are all you need. A PMI-trained project manager might shake their head and patiently explain we need a PRD (product requirements document) and SRD (software requirements document) 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 rigor around how we think through a solution before putting our hands on the keyboard. 

What if the remoteness forced upon us by a crown-shaped piece of chemistry could 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? 

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 toward communication through conversation can coexist in juxtaposition with written documentation. We now have tools that allow for a synchronous, real-time experience of 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, to name a few. Even Microsoft Office has reinvented itself as a collaboration suite. 

Combined with individual and group chat and video calls, aligning on the intent and high-level implementation of a solution is relatively simple. Yes, these tools introduce more friction than swiveling your chair to ask a question, but you benefit from 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, 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 difficult to express my thoughts in writing?" Maybe you're getting into the weeds. "How long 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.

You want to ensure that your artifacts are accessible, meaningful, contextual, small, and modular. This applies using plain language, a data model, an object model, a sequence diagram, or anything else. 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 avoid becoming 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.

Where to start

There is a range of the quality and suitability of the tools you may choose to create and maintain your artifacts collaboratively. Spend some time evaluating 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 reasonable 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 meet your needs. After all, there is 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.