Clear, organized, and easy access to information is critical to supporting team growth and promoting the kind of culture change that we, the U.S. Digital Service, and fellow Innovators and Early Adopters aim to produce throughout federal IT development. As a small step towards that goal, we’d like to announce the 18F Hub, a Jekyll-based documentation platform that aims to help development teams organize and easily share their information, and to enable easy exploration of the connections between team members, projects, and skill sets. It’s still very much alpha-stage software, but over time, we’ll incrementally improve it until it serves as the go-to place for all our team’s working information, whether that information is integrated into the Hub directly or provided as links to other sources. It also serves as a lightweight tool that other teams can experiment with and deploy with a minimum of setup.
While we strongly believe in the value of transparency and collaboration across government, the details of our team, our projects, and our activities aren’t the real reason we’re launching the Hub: the exposure of our domain knowledge, working models and processes through tangible artifacts that people can adapt to their own environments is. We hope that these tools and artifacts will act as force-multipliers for our mission of changing federal IT development culture, and serve as key infrastructure for standing up digital services teams in other federal agencies. Despite still being in its very early stages, we hope making the Hub available now will plant the seeds of culture change farther and wider than would otherwise be possible.
Motivation
The concept of information-sharing systems within an organization isn’t new. I was first exposed to snippets and other internal systems at Google. The Consumer Financial Protection Bureau has developed an open-source collaborative intranet framework, as well as an idea box tool. Plus, wikis are everywhere.
Why create another information-sharing platform? Simplicity. The Hub tries to make it easy to share and discover team information with a minimum of complexity, and to make it easy for other teams to set up their own local Hubs. While it may not scale up to an organization of thousands of employees, for small companies or teams up to a few hundred, the fact that Jekyll generates static HTML pages based on imported CSV and YAML files means that such groups can stand up their own Hub instance without the burden of administering a full-blown web application.
Goals
What follows is a list of specific goals the Hub aims to achieve. The Hub is still far from the mark on some of these, but this should serve as a roadmap for where we’re headed. Look for changes and improvements in the coming months that step us even closer to these goals!
Ease of perusal
The core feature of the Hub is easy navigation of team information and documentation behind a centralized interface. When it is easy to find information about your team, it becomes much easier for new members to get up to speed, and for existing members to stay abreast of new information as the team evolves over time. Knowledge-sharing scales, as a standard documentation platform makes up-to-date reference material immediately available to the entire team (and possibly beyond). Spontaneous connections leading to productive outcomes become more frequent, as such connections can happen without the need for direct interaction or supervisor facilitation.
For example, through the team member interface, you can see an 18F member’s projects, location, working groups, skill sets, and latest snippets. Each of these pieces of information is cross-linked, meaning that you can meander from one piece of information to the next. You can find everyone who’s working in Washington, D.C., what projects they’re working on, what the latest update to that project is, and more.
Ease of demonstration
Imagine what it would be like to have a Hub running for your team. Since there’s no substitute for hands-on experience, we encourage people not only to browse the 18F Hub, but to run the Hub locally on their own machine to see and feel what it’s really like. Anyone familiar with a command-line interface and who has access to GitHub and RubyGems can clone the Hub repository and have a demo instance running in five commands:
$ git clone git@github.com:18F/hub.git
$ cd hub
$ gem install bundler
$ bundle
$ bundle exec jekyll serve
This will produce a running instance of the 18F Hub on your own machine. From there, it’s fairly straightforward to replace 18F’s information with your own by updating _config.yml and the files within the _data and pages directories, creating a concrete glimpse of how the Hub can transform the way your team shares information. We’ll be developing tools and documentation to make it easier to figure out how to configure and modify the Hub as development continues.
Ease of contribution
Most Hub pages are directly editable using GitHub’s in-browser editing features. Since GitHub is such a popular collaboration platform among open source developers, and 18F developers and designers rely heavily on GitHub for their day-to-day workflow, it’s relatively easy for our team members to submit updates to Hub-based documentation. We hope this model will prove viable for other teams as well.
Of course, the Hub is not the most natural fit for all team documentation; it works best for relatively stable information. There are more natural media for collaborating on drafts, collecting meeting notes, sharing files, or any number of other tasks. The Hub also tries to make it easy to incorporate links to these other documentation sources, no matter where they are, so that the overall set of useful information available to the 18F team is all organized and available with a minimum of effort through the Hub.
Ease of development
Jekyll is very well-documented and has gained in popularity over the years; choosing it as the foundation for the Hub enables other developers to make sense of the code and content structure very quickly. 18f.gsa.gov is itself developed using Jekyll, which means the Hub fits right in with the existing experience and skill set of many 18F developers and designers.
The Ruby programming language in which Jekyll is written allows for very rapid prototyping. The Hub takes advantage of Jekyll’s support for imported data files to import snippets from CSV files and lists of team, project, and other data from YAML files. The Hub uses Jekyll plugins to manipulate the imported data and generate highly cross-referenced pages. I incrementally developed the Hub over my first two months on the team, incorporating feedback from my 18F teammates as they too began to see the potential of such a tool.
As the project gained momentum and moved from the “Exploration” phase into the “Settlement” phase, in which certain features and interfaces began to stabilize, I started adding automated tests with every new code change. Given comprehensive automated tests and the RubyGems packaging scheme, I began extracting generally-useful, reusable components, such as hash-joiner. I anticipate extracting more of the plugin code into gems over time, leaving the remaining plugins very lean, readable, and easily-adaptable to the needs of other Hub adopters.
Ease of deployment
Because Jekyll is a static website generator, there are no other frameworks to install or databases to provision, deploy, monitor, or administer. Once the site is generated, it can be served locally by Jekyll itself, copied to an available server running Apache or Nginx (e.g. using the widely-available rsync command), or automatically deployed using GitHub webhooks (again, just like 18f.gsa.gov).
Run your own Hub!
This alpha-stage version of the 18F Hub is only our first shot, but we eagerly hope to see other teams launch their own Hubs, publish snippets, organize ad-hoc working groups/guilds/grouplets, and share their own innovations with the world. Clone the GitHub repository and follow the README instructions to get started!