Like code bases, the policies and best practices making up a company are collaboratively developed and owned bodies of text. Github is an excellent platform to develop both with a large group of collaborators. The company I currently work at (Originate) uses GitHub as such an intranet platform. This enables an unprecedented level of collaboration, but more importantly empowerment and transparency for all employees.
Over the past ten years, GitHub has evolved from (arguably) the best software development platform into one of the most productive general-purpose collaboration and community platforms that can develop all sorts of content, not just source code. The GitHub team has spent significant efforts making almost the entire functionality of GitHub easily accessible to non-technical users via GitHub’s web interface.
Today, a lot of people use GitHub for a lot more things than developing software. Thousands of communities, like for example ReactJS, use it as a content management system for their websites and blogs. GitHub is used by data scientists to collect and share datasets. An example is the public data sets of the General Services Administration. Countless non-technical communities like LegalMattic or the Open Austin project collaborate on GitHub and combine many forms of non-technical knowledge. Hundreds of legal entities such as governments or companies engage with the public by developing policies in the open on GitHub. The German parliament (the Bundestag) publishes all German laws on GitHub. The District of Columbia develops its legal code on Github, giving the public a chance to correct mistakes online.
Many companies use GitHub as an intranet. An example is MapBox. They built their own intranet solution, but employees ended up preferring to use GitHub directly for communication and collaboration. Originate also uses GitHub as an intranet. Let’s take a closer look at how exactly we do that.
GitHub is a platform built around a combination of several brilliant concepts that make collaboration as efficient as possible:
On a basic level, GitHub is nothing more than a shared folder in the cloud, containing files and subfolders that can contain text, image, and other data files. Git’s primary use case is downloading the files and folders to your computer so that you can edit them locally, but that is not relevant here. Originate’s intranet uses GitHub’s web interface.
GitHub’s web UI shows previews for many common file types like text, images, PDF, Photoshop, etc. When browsing a folder on GitHub, you see a list of the files in that folder, buttons to create or upload new files, followed by a preview of the default file (called
If you browse a file, you see a preview of that file and buttons to edit or delete it. GitHub can be configured to require a review and approval process for such changes.
There is a mobile web view, but mobile phones can also display the desktop UI when in landscape mode. GitHub can store very large files efficiently using the Git-LFS plugin.
Putting all this together, Originate’s intranet consists of rich text files, images, and PDFs that are browsed directly using the preview functionality of GitHub’s web interface. We use Markdown as the rich text format since it has become the lingua franca for rich text and can be learned in less than an hour even by non-technical people.
GitHub is just the starting point. Not all content has to be stored in it. GitHub can also link to other web pages like Google Docs, Sheets, or Slides.
Browsing Originate’s intranet is similar to browsing a website. People usually drill down from the homepage. GitHub’s main menu entries correspond with the main activities that are done on the intranet:
There is also a simple full-text search using GitHub’s code search feature.
Let’s look at editing content. Originate is a collaborative organization that everybody helps define and shape. Our best practices represent consensus. Leaders decide the overall direction, people “on the ground” fill in the details because they know best what works and what doesn’t. In this context, many changes are proposed, discussed, and agreed on by the team. An important reason for choosing GitHub is that it makes this workflow extremely efficient.
Let’s look at a concrete example for how this looks like in practice. An employee, let’s call her Alice, finds the sprint planning meetings in most engagements disorganized. Rather than complaining, she decides to help fix this issue by sharing her template for running these meetings with others in the company. Her journey without GitHub would look something like this:
Sounds familiar? Small changes that require so much bureaucratic effort are uneconomical for the company. As a result, most of these small improvements don’t happen at all. Most of the guides on the intranet are incomplete, outdated, and not in sync with reality.
Let’s see how the same process plays out when using GitHub as an intranet:
Collaboration infrastructure like GitHub enables new levels of teamwork that are impossible with the 20th-century technologies (email, docs, slides) that we typically use. Let’s look at a few aspects in more detail.
Collaboratively developing best practices isn’t easy. We could go the Wiki route and give everybody write-access to the entire intranet. The problem is that without some oversight people will inevitably put things in the wrong place or add half-baked ideas that don’t have widespread support. The content and structure will get messy. Cleaning things up creates even more chaos because it breaks deep links and people won’t find the information they put online anymore.
To prevent this, we could lock down the intranet and give only a small group of editors write access. We have seen in the example how clunky this model works because it introduces bottlenecks and the need to copy-and-paste content between email, slides, chats, documents, and the intranet while proposing, discussing, and implementing policy changes.
The most ideal approach, as shown in the example, is the code owner model: Everybody can implement and propose ideas, owners for each file review them and ensure that changes are correctly structured. That’s a lot less work for the code owners, preventing them from becoming bottlenecks. This model works incredibly well for software development on GitHub. It can apply similarly well to documentation as long as this documentation is represented as code.
“Transparency helps us vet the best ideas no matter where they come from. GitHub helps us scale that.” — Lindsay Young, Mapbox
Open source combines the technical expertise of millions of developers worldwide. Our collaborative intranet uses the same mechanisms to combine the collective experience of the entire company. All of Originate’s processes are documented on our intranet. Anybody who is interested in how we do things can look it up. Anybody who sees areas for improvement can propose how to do things better. This creates a high degree of transparency for the company.
Proposing changes by modifying other people’s documents directly would be awkward. Suggestions inside a Google Doc can make the document temporarily unreadable for everybody. On GitHub, changes are made on a copy of the document, without affecting the main version. Changes are just proposed, with the option to have a conversation and adjusting the proposal before the document owner makes the changes visible to everybody. This is a much nicer collaboration model.
Git’s powerful versioning features keeps previous revisions of content around, together with information who made which changes. This tells us who introduced certain policies and in which context. Knowing this helps improving or cleaning up outdated policies because it gives us additional clues who to talk to about them. The list of people who have contributed to particular documents on GitHub is also a good starting point to identify domain experts in the company.
A GitHub-based intranet is pretty “techy”. That’s a good thing and intentional:
Second, Originate lives and breathes technology-based innovation. It is our main product. Technology is at the core of our business and culture. We engineer our success, even our internal processes and their documentation! Many of our non-technical employees are proud that they are also coding on GitHub, in plain English using Markdown.
All our intranet content is stored in an open, standardized format (Markdown) on an open platform (Git). There are many third-party tools available. There is no vendor lock-in. This ensures long-term availability. It is easy to get all information out of GitHub when the need arises. Many third-party Intranet-as-a-service solutions will not be around in a few years. Platforms that store and visualize Markdown using Git will be around for decades.
Last but not least, Git and Markdown focus on being simple rather than easy. This is an important distinction. Many tools try to be easy to use by automating the typical use case as much as possible with all sorts of magic (technology that we don’t understand) so that the human has to do very little. There are, however, always edge cases where we need to go “against the grain” and do things differently than how the magic inside the tool works. In those cases, it is often not obvious or even possible to make the complicated mechanisms inside the tool do what we want. These edge cases make heavily opinionated and automated solutions that try to be too easy actually harder to use in real life. Good magic that makes things easy and doesn’t get in the way is very hard to get right.
It is therefore often better to use simple systems. A tool is simple when it is always clear and intuitive how things work under the hood and how to make the tool do what we want, even relatively complex things. The price of simplicity is that doing something can take a few more steps to accomplish. But at least everything works all the time and there are no surprises at the eleventh hour.
Simplicity also allows for flexibility. GitHub is generic enough to replace not just our old Google Sites based intranet, but also the old content management systems for our website and the blog. Now we have to learn and maintain only one simple system instead of three “easy” ones. Overall that’s a lot more economical and less complex.
No solution is perfect and GitHub is no exception. A full-text search exists but is clunky. It is not possible to add comments to existing content outside of pull requests. The GitHub UI could be made a bit more polished and intuitive. Using GitHub isn’t difficult, but a lot of non-technical people, all the way to top management, struggle with the unfamiliar look and feel of the current GitHub UI. All these things are solvable with a bit more UI polish and WYSIWYG editing of Markdown.