The work you produce and share is embedded in a network of context and knowledge. If you want to collaborate efficiently, leave breadcrumbs for your collaborators to access the context supporting your work.
Knowledge work is a creative and collaborative effort. The collaboration that goes into shaping a piece of work might not always be of the elbow-to-elbow, synchronous kind, but it’s still there. Think of software developers opening pull requests, authors sending their drafts to editors, or CGI artists working on different steps of an animation pipeline. They might not work at the same table but they still build on each other’s work.
For collaboration to be successful, all those involved need to share as much context as possible. That’s because knowledge work is ambiguous. There is no right way to solve a problem, only tradeoffs. Understanding the tradeoffs and their rationale is crucial for aligning decisions and moving work toward the chosen destination.
One way to help everyone be on the same page is to leave context breadcrumbs.
Compare these two descriptions for a fictional pull request. Option 1:
Fixes a crash when the “show more” button is pressed on a resource with 10 or more elements.
Option 2:
Fixes a crash when the “show more” button is pressed on a resource with 10 or more elements by using the appropriate fetch API for that kind of resource.
@useridentified the crash. Here’s a link to the crash report:link.You can also see how many users have been affected in production from this dashboard:
link.The crash occurred because we were using the standard API to load the resource,
link to API doc, but for entries with more than 10 elements, we should have used the paginated version,link to API doc for paginated version.The resulting code is more complex because of this conditional behavior.
A simpler alternative could have been to cap the number of fetched elements to 10.
I think this implementation is better because limiting the number of elements we show would go against the point of a “show more” button.As a reminder, the “show more” button was introduced as part of the “richer information” project,
link.
Option 1 is short and concise but only tells the reviewer what the code does. Option 2 is long but gives the reviewer additional information to understand why the change was necessary and how that part of the app fits within the overall product vision. On top of that, by mentioning the alternative option, the author preemptively addresses possible a reviewer might have.
Notice how, in Option 2, the author added links to supporting material. The links act as context breadcrumbs. They take the description to the next level because they allow readers to reconstruct the broader context in which the PR exists without relying on the author’s synthesis.
Context breadcrumbs front load information to avoid unnecessary back and forth. To make collaboration efficient, your colleagues should be able to take action on anything you share without asking you any clarification questions. For that to happen, you need to make it as easy as possible for them to access all the context they need to understand what needs to be done.
Reducing back and forth is crucial to iterate fast. This is even more true for organizations distributed across time zones. When each exchange has 12 hours round trip, it takes only a few to destroy a project’s momentum.
Leaving context breadcrumbs also reduces hand-over costs. When someone needs to pick up where you left off, they’ll have all the information they need within reach. And when you consider the person who will need to continue your work might end up being your future self, you have even more incentives to make their job easier.
Reducing hand-over costs and increasing collaboration efficiency are only first-order effects of the practice. When implemented consistently over time, the context breadcrumbs bring a deeper, more powerful contribution to everyone’s ability to collaborate.
A network of knowledge emerges from the context breadcrumbs. Its nodes are all the documents, RFCs, pull requests, and anything else referenced by URL. This is the biggest payoff and goes beyond improving efficiency.
Once a knowledge network is in place, those who can traverse it will have access to all sorts of background knowledge and past experience. You can tap into the network to understand the strategic decisions behind the current iteration of the product. You can uncover choices that introduced path dependence and sunk costs. You can learn from past mistakes or stumble upon ideas that were put aside but are now ripe for implementation. With some patience and effort, you might even discover insight you can leverage.
One response to “Leave Context Breadcrumbs”
[…] a clear explanation of your changes, why they are needed, and the tradeoffs you considered, and to leaving context breadcrumbs to help reviewers access all the supporting information that shaped your […]