We Built a Collaborative Documentation Site. Deploy Your Own With the Push of a Button.

By The Times Open Team

By Isaac White, Andrew Fischer and Suzanne Wang

Illustration by María Hergueta

Maintaining useful documentation is hard. Whether it’s tips for running a program, publication guidelines or company rules, keeping track of resources can quickly become unwieldy. This is especially true at larger organizations where thousands of people care about similar tasks: It’s easy to end up with silos of duplicated instructions that only small groups of people know about.

The New York Times is no different. Several years ago, it was common for each desk to have an internal wiki that they used to collect these instructions. As the use of Google Docs grew within the newsroom, the wikis began to be used and maintained less frequently, and knowledge of existing documentation became scarce. When the older wikis were shut down in 2017, several teams that often collaborate realized we no longer had an effective strategy for sharing documents across the newsroom. We realized we could do better, and decided to build a centralized tool, called Library, that would host our documents in a way that could be shared across the newsroom.

Our solution to this problem has worked well for us. We hope others will find value in the technology we built, so we’re releasing Library to the open source community.

Library is a wiki powered by a Google Docs backend. When you connect Library to a shared folder or team drive, it will traverse the documents in the folders and create your site content. Documents in Library are searchable, taggable, and can be grouped by desks or categories.

To add a page to Library, you simply create a new Google Doc, or move an existing document into the folder or team drive that powers Library. Existing pages feature a convenient link that enables quick access to the Google Docs interface for any particular document, and editing the Google Doc makes changes to the page in Library.

Powering a website based on Google Docs might seem like an odd choice. Plenty of other solutions for wikis provide their own interface to edit content and are self-contained. But many desks in the newsroom had already begun keeping their notes in Google Docs, so we wanted to meet people where they already were, rather than trying to teach them something entirely new.

Using Google Docs as the editing interface for Library helped us create a living repository of documents, how-tos, tips and guides that everyone could contribute to. It already provides a robust set of tools for document history and real time collaboration, which makes it an ideal editing interface for a wiki.

With the editing interface handled by Google Docs, we used the Google Drive API to retrieve the content from each document and render it inside the wiki. Instead of just showing a list of links to Google Docs, Library provides a clean interface for viewing and navigating between those documents.

Our intention with Library’s browsing experience was to make it as intuitive as the editing interface. We anticipated that most Library users would be looking for documentation by keyword or phrase, so we placed a search bar as a prominent element on each page. When a user searches for a document, the results will include relevant documents, annotated with information about who last edited it, and where in Library the document is stored. For users who would rather explore specific topics, there is a “View All Docs” page that will list the top level of each folder in Library by category.

A basic version of Library works “out of the box” without the need to write any code. To demonstrate the features of Library (and facilitate an easy deployment pattern) we’ve created a “Deploy to Heroku” button that is accessible through Library’s Github README page. Clicking the button will guide you through how to set up a new Library instance. Deploying to Google App Engine is also supported, via the instructions on the documentation site.

With a little code knowledge, you can customize the site language, create themes or use a specific authentication method. We’re also releasing a Docker image, which more advanced users may find useful for deploying in other environments. Library can be deployed with or without an additional customization layer, and we encourage you to explore the example to see how easy it is to use.

We’ve been collaborating with Northwestern University’s Knight Lab to alpha-test this release (special thanks to Maxine Whitely and Joe Germuska for their feedback). In the spring, the Knight Lab will be piloting an internal Library for student use. We plan to partner with the Lab to expand Library’s features and explore other uses for Library in the news community.

To contribute to Library, check out the README on Github and consult the contributor guide. For more information about what Library can do and a demonstration of a running copy, consult the sample deploy. We’re looking forward to collaborating with you.