A collaborative GitHub-based intranet

tl/dr

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.

GitHub is a collaboration platform

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.

how GitHub works

GitHub is a platform built around a combination of several brilliant concepts that make collaboration as efficient as possible:

• Git is an extremely capable tool for co-creating textual content as a team and tracking who changed what when
• pull requests are the ideal form of asynchronous collaboration
• an open platform architecture allows to extend GitHub’s built-in functionality via bots and third-party services
• open document formats like Markdown enable a vivid ecosystem of tool support

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 README.md).

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.

GitHub as an intranet platform

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 the intranet

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:

• code leads to the documentation
• issues leads to company-wide action items, questions, or discussions
• pull requests leads to current or past improvement suggestions
• insights leads to statistics

There is also a simple full-text search using GitHub’s code search feature.

editing content

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:

1. Alice isn’t sure who is responsible for changing the official structure of these meetings. Furthermore, what is the best way to reach this person? Write an email? Call? Set up a meeting? Should she prepare a slide deck with background on her ideas? If it is a high-level person, is it okay to bother them with such details?
2. With the help of her supervisor Bob, they find a VP-level person who feels responsible for this and can be convinced to help. Let’s call her Camilla.
3. They hop on a 30-minute call where Alice walks Camilla through her idea for a better meeting template and explains why some elements of it are important. Camilla replies with: “Okay, let me bring this up in the next leadership meeting to see how the other teams feel about this.”
4. Most of the time this would be the last time Alice hears about this. Camilla isn’t really a passionate champion for this effort. She doesn’t participate in sprint planning meetings herself, so to her working this out with the other teams is just another chore in her already busy schedule. She cannot make a convincing case for Alice’s agenda to the other teams, and there is too much back and forth and concerns “where this is coming from” for her to push this through the office politics.
5. Assuming we make it past this point, now we need to find somebody who has admin access to update the intranet with the new sprint planning guide. Let’s call him Don. We have to explain to Don again what exactly we want to change. These things take time and require a number of back-and-forth as well as follow-ups and reminders.
6. The new agenda is perceived as useful by many teams. Bob and Camilla take credit for “helping make it happen”. The process took weeks. Alice has spent several work hours as well as a number of private evenings reaching out to a number of other team leads and working out the details with them. She comes to the conclusion that such changes just aren’t worth the amount of effort they require. Next time she will just share her ideas with some friends.

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:

1. Alice goes to the intranet, finds the guide for sprint planning meetings, hits the edit button, adds her proposed template, and submits a code review with this change. This takes her 15 minutes including formatting the thing.
2. GitHub automatically tags Camilla in the pull request, because Camilla is listed as a code owner for the sprint planning meetings. Camilla gets an email notification, takes a brief look at Alice’s changes, and tags a number of other team leads whom she would like to make this decision as a group. This takes her 3 minutes.
3. The pull request sees a constructive conversation amongst the team leads. People thank Alice for the initiative, confirm that most of the sprint planning meetings are indeed inconsistent, and add ideas what else could go into this improved meeting agenda. Alice is surprised about the amount of momentum her suggestion has created and learns a few things that help her run her own sprint planning meetings better.
4. Once the group agrees on using the new template, Camilla merges the pull request. This updates the official sprint planning meeting guide on the intranet with Alice’s changes. No Bob and Don needed here.
5. The new agenda is perceived as useful by many teams. Alice gets the credit for it since she initiated the pull request. Alice feels that this was quick and fun, and hopes she can do this again at some point.

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.

code owners

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 and empowerment

“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.

history, traceability

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.

increasing tech literacy

A GitHub-based intranet is pretty “techy”. That’s a good thing and intentional:

First, software is the new math, meaning it is becoming so universally useful and dominant in our lives and the economy that those who aren’t familiar with it have a serious disadvantage. We want to make everybody more comfortable and fluent in at least the basics of it. Learning to program documentation-as-code is a great entry into the world of programming. It’s less of a learning curve and more useful to a non-developer than learning a general-purpose programming language like Python or JavaScript would be.

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.

openness and long-term availability

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.

simplicity and flexibility

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.

areas for improvement

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.