Why everything should have a URL

TL;DR: By naturally capturing and exposing process and sharing it as widely as is appropriate for the subject matter, URLs render organizational context time and location agnostic allowing knowledge to move more freely within an organization on an asynchronous, discoverable, and opt-in basis.
11 minute read

At GitHub, there’s an ironically unwritten mantra that “everything must have a URL”. While that’s obviously a bit of a hyperbole, there’s something to be said for preferring systems that naturally capture and expose process, and thus preferring systems that can render organizational context time and location agnostic.

You see, humans have a terrible fidelity for retaining historic context, deliberative process, and decision pedigree. As an organization works towards its mission — be it a three-person team or an entire company — discussions are held, decisions are made, and ideally, artifacts are created as a result. The problem is, most often, those decision artifacts focus on what decisions were made, not who made them, or more importantly why.

Today’s default workflow

Most organizations today transact business almost entirely through email and in-person meetings. Absent an additional step whereby participants go out of their way to capture and share context, organization knowledge primarily lives in two places: in employees’ heads, and in their inbox. If that employee leaves the organization, or if they win the lottery and don’t show up on Monday (read: bus factor), a significant amount of information — information essential to the organization’s continued operation — leaves with them.

Think through some common scenarios where a team member might need to gain additional context they weren’t originally privy to: they could have been out of the office when a decision was made (humans do silly things like getting sick or making other, smaller humans), they could have been on a different team at the time, heck, maybe they weren’t even part of the organization at the time. Whatever the reason, they became a stakeholder mid-decision or post-decision, and thus lack the context necessary to properly participate going forward, especially not on equal footing.

How is that essential context shared? In many organizations I suspect the answer is “I guess you had to be there. I think Bob was there that day, you should go ask him”. Assuming you can find Bob’s desk, he’s in the office that day, free now, and remembers a meeting that potentially happened months or years earlier, you might be able to get your question answered, but that process doesn’t scale as people constantly move around and new team members are onboarded. Bob could hunt through his inbox and forward a stream of emails for you to read through in reverse chronological order, but that’s likely neither efficient nor very helpful for either party involved (“can you forward me the attachment?”).

Systems that naturally capture and expose process

Theoretically, you could have a dedicated cadre of scribe-stenographers to sit in on every meeting, email thread, and water cooler conversation, recording what was said and who said it, or you can create an equally onerous culture whereby decisions are extensively memorialized after the fact by force of habit, but in an increasingly technology-centric world, it makes more sense to lean on computers to do the heavy lifting by adopting systems that naturally capture and expose process as your organization goes about conducting its day-to-day business.

Obviously certain types of conversations — interpersonal conflicts, brain storming sessions, and professional development one-on-ones, to name a few — are much better suited for higher-fidelity mediums like in-person meetings, phone calls, and video conferences. But the vast majority of office communication, especially technical discussions (be they legal code or software code) and those related to decision making, can and should be shifted to more modern, asynchronous tools. Think Slack, GitHub issues, or Basecamp.

URLs are how we share information today

Hundreds of years ago, the way humans shared information was through storytelling. Writing and the printing press shifted things towards written communication (passing around dead trees to share information), and the internet shifted us once again to the digital. Today, the primary means of sharing information with another human is through a URL. Maybe in 10 years we’ll have virtual 3D worlds and you’ll describe directions to walk to a virtual location to get information, but for now, URLs are the primary means by which an idea can be widely shared, and it does so by assigning a globally unique identifier to each. Want to share a New York Times article? Send them a URL. A product on Amazon? A funny Tweet? Whether you realize it or not, every major online system we use today creates unique URLs for each distinct idea.

Ask yourself this: Has your organization’s workflow changed much since the Cold War? Since the advent of the internet? If you swapped out your laptop for a typewriter and email for inter-office couriers would the way you work be all that fundamentally different? From video conferencing to a distributed workforce to real-time chat, the tools available to organizations have radically shifted. Shouldn’t our workflows improve as a result of that shift, at least a little?

The value of giving concepts URLs

Regardless of the tool or technology employed, when process is captured and exposed through a URL a few things naturally happen:

  1. URLs serve to record what decision was made, who made it, and why. They alleviates the need for “you had to be there” and “go ask Bob”-type inquiries. It provides a single, incontrovertible source of truth for the organization’s intentions, and equally important, exposes the reasoning behind the decision, reducing the tendency for top-down decisions to be communicated as “because I said so”. In the military, this is the concept of commander’s intent, and it provides organization members with the context to continue the mission despite evolving circumstances. Process artifacts also naturally capture what other alternatives were considered but ultimately rejected, preventing the organization from rehashing the same conversation six months (or six years) down the line.

  2. Giving process a URL forces the moving party to distill their ideas down into written form, to capture the essential elements of their proposal, and to articulate them in the clearest way possible. There’s a reason it’s called “reducing something writing”. It forces you to maximize the signal to noise ratio and focus on what matters. Once in written form, in addition being more potent, those ideas suddenly become scalable. A meeting room can only fit so many people, and an all hands can only accommodate so many time zones, but given the right technology, the effort required to articulate an idea in writing to one person is the same as the effort required to articulate that same idea to a million, regardless of time or location. URLs allow ideas to spread organically.

  3. URLs provide organizations the ability to link related concepts, to reference prior art, and to ground discussions in the tangible. Once decisions have URLs, related decisions can reference one another, creating an interconnected web of the organization’s collective knowledge. Decisions rarely happen in a vacuum and the ability to reference prior (or dependent) decisions — with the full context immediately available to those who click the link — becomes immensely valuable to grounding discussions in concrete specifics. It’s no longer “Alice would want us to do X”, but “here’s what Alice has already said on the topic”, or “here are the latest numbers Alice ran last week”. Especially when discussing technical matters – be they software, financial, legal, or administrative – being able to easily bring images, charts, and other quantitative resources directly into the discussion grounds the discussion in facts, not opinions, and increases the velocity of decision making by reducing the blocking synchronicity of traditional means of access to organizational knowledge.

  4. URLs allow stakeholders, whether directly or tangentially affected by a decision, to opt-in to an infinite amount of organizational context. Imagine a typical policy decision. “We’re now putting covers on our TPS reports”. Traditionally this edict might be handed down in a PDF’d memo on company letter head (printed, signed, and scanned of course to make it “official”). Those affected get only the context provided by the memo itself, which because it requires an additional step to expose the process surrounding the decision, often includes only the final outcome and the means to carry it out, not why it was made or how. If instead, that decision were posted to an internal company blog, with a link to the forum in which the relevant decisions were made, not only would that provide instantly more pedigree, but suddenly anyone affected - delighted or disgruntled - can freely opt-in to as much or as little context as they’d like, increasing the likelihood of genuine buy in and organization-wide alignment, an alignment that can now transcend the superficial.

  5. URLs enable asynchronous and distributed workflows. URLs are inherently asynchronous. While most of their value comes from the opportunities afforded by their archival nature, but in the short term, they allow teams to capture day-to-day information, and share that information across working styles, timezones, and geography in near real time. Moving discussions from meatspace meetings to asynchronous mediums like chat and issues make those conversations less exclusionary (for example, only those that could physically be in a particular room at a particular moment), and allow distributed stakeholders to participate on equal footing. It’s hard to imagine a distributed or asynchronous workflow that doesn’t rely heavily on URLs. Sure, you could theoretically have a distributed but synchronous team, conducting business through regularly scheduled conference calls, or an asynchronous team that works exclusively by email and other non-linkable means, but both would be far from an evolved workflow, let alone the ideal, especially for those for whom attending in-person meetings are not an option.

URL does not mean public free-for-all

Giving a decision the respect of a URL, does not mean that all of a sudden the details of that decision must be broadcast to anyone in the world (or even the organization), or that you’re inviting a YouTube style comment section. Having a URL is distinct from both the scope and culture in which something is shared. A URL can be exposed to one, two, a hundred, or six billion people. Just as you can control who has access to your bank account, Facebook photos, or company intranet (all things that have URLs), so too can you control who has access to details of a given process. This happens in a few ways:

  1. Participation - There’s no reason a URL can’t be read only. A great example of this is a chat transcript, if you use something like Slack. You can link to any line in the history of a conversation, to provide others with context as to what was discussed, but those reading the conversation six months after the fact have no expectation of being able to reply or participate within the same context.

  2. Scope - You can expose context to a select group, without exposing that context to the entire world (or even the entire organization). Just like in real life, not everyone is invited to every meeting, and not everyone should have access to the details of every decision. Providing something a URL does not change what’s appropriate to share. Salary negotiations and interpersonal disputes should be limited to the employee, HR, and their direct supervisor. Legal decisions should be shared within the legal team, but regardless of the scope, the value of the URL remains the same. It’s far preferable for there to be a digital record capturing who, how, and why each decision was made, available to those that were part of the decision, than for it to only exist on paper, in the hallways, or in unspoken sentiment, which a flood, career change, or memory lapse can wipe out entirely (and isn’t shareable as other members leave or join the team).

  3. Time - You can have a URL that exposes context after the fact. In the open source world, this is common as developers “open source” a project, and its associated revision history and discussions when a formal milestone is reached (e.g, “v1.0”), and well after many crucial design decisions have been made. As with the above example, if the executive team decides that all TPS reports should now have cover sheets, assuming there’s nothing personal about the discussion, there’s no reason they can’t make that decision in private, and share out the context as they share the decision, allowing the entire organization to stand on equal footing in terms of access to organizational knowledge as to why the decision was made and how.

My colleague @bkeepers uses the analogy of a photograph. Photographs capture a moment in time. It may be your family trip to Disney World, what you had for lunch, or something more risqué. You take the photo because you want to capture the moment, but who you share that photo with, and when, is up to you. The important thing is that the moment is captured. That photo being captured doesn’t mean others can (or should) second guess your decision to visit Mickey, that you should have invited your extended family, or that you need to post it online for the world to see.

Fostering an appropriate culture

As with most issues of organization change, the technology is the easy part. The true challenge comes in fostering the appropriate culture. This happens in three ways:

  1. Capturing process - There’s a challenge in creating a culture whereby organization members appreciate (and prefer) mediums that naturally capture and expose process. It’s easy to bump into someone in the break room and brainstorm a new initiative, but to realize the value described above, that idea needs to be captured and memorialized in a higher-fidelity, asynchronous medium. And even if the idea occurs in a discussion in chat or GitHub issues, new employees need to be socialized to how to use those modern collaboration tools, and more importantly, why, in many cases, they should be preferred to in-person, meetings.

  2. Responsible participation - There’s a challenge in creating a culture in which organization members appreciate their responsibility to participate responsibly. Just because you can participate in a discussion, doesn’t mean you should. Most new hires face this problem as they’re introduced to GitHub’s workflow internally. There’s a firehose of information that’s immediately made available to you, and you must learn to prioritize what matters to your role, and why, or risk drowning in an onslaught of information. That same risk is true on the flip side. The potential for Monday morning (and Tuesday, and Wednesday morning) quarterbacking increases exponentially as an organization grows, and without the proper cultural framework, transparency can quickly become seen as unproductive, inefficient, or a political liability.

  3. Necessary tooling - As my colleague @spraints aptly points out, URLs are still very technical. As ubiquitous as URLs are, not everyone can publish something to the intra- or internet. The tooling has gotten better — projects like WordPress have done much to democratize the internet — but even the acronym URL is still intimidating if processes don’t naturally create them. Much like RESTful APIs did for data, most critically URLs provide a standard means for teams within a company to define their interface to the rest of the organization (or the world). URLs provide a human-API to answer questions like “where can others look for your work output?” and “where can others ask questions or start a conversation with your team?”. URL-centric organizations go out of their way to provide non-technical teams with the means to create process-capturing URLs within the context of their natural workflow.

Knowledge work as craft

Whether you’re an attorney, a civil servant, or a web developer, in today’s digital world, if you don’t make sprockets for a living, there’s a good chance that you’re a knowledge worker. Your deliverable at the end of each day, doesn’t actually exist beyond magnetic patterns on a hard disk. Through meetings, discussions, and drafting, you create organizational knowledge in one form or another.

Just as blacksmiths know the value of an anvil, and bakers the value of yeast, so too must knowledge workers embrace the tools of their craft. A composer would never stand for his or her concerto being played on a kazoo. Why then, is content all-too-often created haphazardly, with its presentation and preservation being subject to the whims of organizational habit?

“Everything must have a URL” does not necessarily mean that everything must be public nor does it mean that the peanut gallery should have an opportunity to critique every decision you make. So long as URLs are the primary means by which we share information today, “everything must have a URL” is shorthand for describing a system that naturally captures and exposes process, and ideally, for sharing that context as widely as is appropriate for the subject matter. While it’s certainly hard to make the case that absolutely every decision should be rigorously memorialized, it’s even harder to make the case that your organization would be better off if they weren’t.

The next time you begin a new project, adopt a high-fidelity, electronic medium that naturally captures and exposes process through URLs, today, and forever. Your content, your fellow knowledge workers, and the information’s consumers deserve it.

I’d be remiss if I didn’t give significant credit to @bkeepers and @spraints whose many conversations inspired and informed this post (and for putting up with my “kids these days don’t appreciate URLs” rants).

Originally published November 12, 2015 | View revision history

If you enjoyed this post, you might also enjoy:

benbalter

Ben Balter is the Director of Hubber Enablement within the Office of the COO at GitHub, the world’s largest software development platform, ensuring all Hubbers can do their best (remote) work. Previously, he served as the Director of Technical Business Operations, and as Chief of Staff for Security, he managed the office of the Chief Security Officer, improving overall business effectiveness of the Security organization through portfolio management, strategy, planning, culture, and values. As a Staff Technical Program manager for Enterprise and Compliance, Ben managed GitHub’s on-premises and SaaS enterprise offerings, and as the Senior Product Manager overseeing the platform’s Trust and Safety efforts, Ben shipped more than 500 features in support of community management, privacy, compliance, content moderation, product security, platform health, and open source workflows to ensure the GitHub community and platform remained safe, secure, and welcoming for all software developers. Before joining GitHub’s Product team, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage more than 2,000 government organizations across 75 countries to adopt open source philosophies for code, data, and policy development. More about the author →

This page is open source. Please help improve it.

Edit