This summer TTS welcomed Dylan Irlbeck as a Coding it Forward Civic Digital fellow. Dylan worked with the TTS Technology Portfolio and Outreach teams to improve the TTS Handbook. Dylan has offered to share with us a bit of history about the Handbook and how he’s been tackling this project. Take it away Dylan!
Nearly five years after its inception, we realized there haven’t been any blog posts about the primary home for documentation in 18F: the Technology Transformation Services (TTS) Handbook (known affectionately as “the Handbook”). TTS, if you weren’t already aware, is the umbrella organization for 18F and a number of other federal technology programs like the Presidential Innovation Fellows and Centers of Excellence and services like usa.gov and search.gov. The Handbook services all TTS staff, which of course includes 18F.
In a nutshell, the Handbook is our take on internal government documentation. It is an open, crowd-sourced, accessible, and living resource that aims to provide the information our team needs to do their work.
<img src="/assets/blog/image4.gif" alt="Animated GIF of the TTS Handbook homepage and the "Mission, history, and values" page" />
In this post, we’ll unpack the Handbook’s core values -- and how they’re implemented in practice. We’ll dive into our experience with the Handbook and even highlight some other organizations who’ve adopted it. Finally, we’ll touch on what’s in store for the project going forward. If you’re a federal employee, civic technologist, or member of the public, we hope to leave you with a sense of what 21st-century transparency in your government looks like.
Values and implementation
As an organization, the Technology Transformation Services (TTS) is committed to transparency -- for the public and for itself. We prefer plain language over jargon, open- over closed-source, and public over private information. The Handbook aims to reflect these overarching values, and therefore implements the following principles:
- Open: To build trust among TTS staff members, with the public, and to make the information as easy-to-access as possible, content should be open to all. The Handbook is available on a public website, its code is open-source, and we instruct employees that “TTS-wide information should be public by default.” Another benefit of keeping the Handbook open is re-usability. We’d love for other federal and civic organizations to adopt the Handbook, and by keeping the code open-source we encourage just that. (And indeed some civic tech companies have already forked the Handbook!)
- Crowd-sourced: Anyone should be able to contribute. Contributors should not need to know web development or version control, and they should not have to be affiliated with TTS. There has never been an individual team or person responsible for maintaining it, and this is by design: Content is entirely crowd-sourced. To that end, our policy is that anyone can contribute to the Handbook, whether or not they work for TTS. This collaborative culture has resulted in nearly 200 formal contributors -- and hundreds more informal ones -- over the years.
- Accessible: Handbook content ought to be written in plain language and be searchable. We do that by reminding contributors of the 18F plain language guide, and using search.gov on every page. In order to check that proposed changes don’t break accessibility, we use preview branches to give contributors a live website for demoing their changes. As a contributor, this relieves the burden of knowing Jekyll, our static site generator, and having to run the Handbook locally to test new changes.
- Living: Content is expected to change over time. Specifically, it should be kept up-to-date with TTS’s processes and policies. At present, TTS staff members are encouraged to submit fixes for inaccurate or outdated content. These fixes are generally reviewed and accepted optimistically. They are then immediately deployed to the live site via cloud.gov Pages. This tight loop ensures that content is updated as seamlessly as possible.
Our experience
Overall, the Handbook has been incredibly successful for TTS. It reduces a lot of headache with onboarding new employees, results in fewer duplicative questions via email or Slack, and, more generally, demonstrates our commitment to transparency as an organization. The default to using plain language has also been a breath of fresh air for staff. One of our colleagues put it best when they said:
[The] TTS handbook is really, really awesome. I can't think of another organization I've been with that has such comprehensive, easy to use documentation… the handbook empowers a culture of openness, collaboration, and transparency, like we're all working together towards a common good. - TTS Contractor
That said, there have been some challenges. We will briefly touch on three of these, along with the solutions we’ve planned or are currently building (with links to relevant GitHub issues and pull requests -- another benefit of working in the open.)
Challenging contribution process
The actual mechanism to make contributions was overly complicated. Some contributors expressed frustration with Markdown and the lack of tooling for non-technical users. Historically, the Handbook’s content has been edited via Git: contributors would fork the repository, modify some Markdown content, and open a pull request for review. GitHub has a decent interface for accomplishing this, but some basic knowledge of Git and Markdown -- and, to some extent, Jekyll -- was required. This posed a barrier to non-technical people who wanted to contribute.
Solution: To remedy the overly-technical contribution process, we are adding support for NetlifyCMS (via cloud.gov Pages): an open-source content management system that will give our contributors a friendly UI and Git-free publishing workflow.
Reviewer ambiguity
Tethered to unclear ownership is an issue that crops up in the review process: reviewer ambiguity. In order to make content changes, contributors must receive at least one approval from another contributor. But who should that approval come from? Without ownership, answering this question, especially as a new contributor, was difficult. This ambiguity eroded the “liveness” of the Handbook since it caused friction in keeping things up-to-date.
Solution: To address the reviewer ambiguity, we made use of GitHub’s “code owners” feature. Our ownership assignments, from a content and code perspective, are maintained in a CODEOWNERS file. In this file, GitHub teams are assigned as “owners” of certain folders. Later, they are automatically added as reviewers to pull requests affecting their content.
Unclear governance
Under the Handbook’s fully crowd-sourced model, there aren’t always clear content owners -- be they individuals or teams. This troubled contributors because they usually didn’t know who to ask for approval. And it made regular review impossible because no one was accountable for outdated content.
Solution: We are devising a governance structure that will clarify the contribution process, create clear ownership assignments, and enforce regular content review. Our goal is to find a degree of governance that doesn’t endanger our open, collaborative contribution culture.
Other challenges we’ve run into while building the Handbook include:
- Whether content acts as requirements or guidance: We’re a federal organization, and we need to be clearer about distinguishing between the two (and hyperlink to actual policy where applicable).
- Information overload: the homepage has a lot of sections and links, so we’ve been thinking about how to better organize things. Moreover, important information -- such as the Handbook’s values -- are not currently present.
- Inconsistent page structure: there are pages with similar themes (for example, our Software and Tools pages), but they each have unique sections and formatting. We want to create templates to ensure that page structures are consistent.
Forks
Several other digital service organizations have forked the Handbook for their own needs (abiding by the project’s open-source license):
We also know of other parts of GSA and federal agencies referencing the TTS Handbook in the documentation of their own practices. This passive influence is, in our view, a direct result of content being widely accessible.
We always love to hear how people outside of TTS are using the Handbook. Maybe you’ve forked it, read a few pages and had a good experience, or see areas for improvement. If so, please let us know!
Looking forward
TTS envisions a government that provides trusted, modern experiences for all. We’d love to see the Handbook and its values -- open, crowd-sourced, accessible, and living -- be implemented across federal agencies and other civic organizations. As civil servants, we owe it to all our stakeholders to be transparent. The Handbook represents our commitment to openness, and we’re excited to continue iterating on it in the months and years ahead.
If you’re curious about the specific work we have planned, or if you have feedback on the Handbook itself, do check out our issues page. And if you see something that needs fixing, don’t hesitate to open a pull request!
I’d like to close by giving a few words of thanks. To Coding it Forward for allowing me to participate in their Civic Digital Fellowship. To the Tech Portfolio and Outreach teams, and TTS as an organization, for being so welcoming and encouraging throughout my fellowship. To John Jediny and Aaron Borden for providing invaluable technical guidance and words of encouragement. Finally, to the mentors that have made my summer in government an overwhelmingly positive experience: Aidan Feldman, Star Vanamali, and Andrea Sigritz.