Open collaborative writing with Manubot

Daniel S. Himmelstein, Vincent Rubinetti, David R. Slochower, Dongbo Hu, Venkat S. Malladi, Casey S. Greene, Anthony Gitter

Abstract

Traditional scientific publishing often relies on static documents and opaque collaboration processes, leading to versioning conflicts and limited reproducibility. Manubot is an open-source system that applies software engineering principles—specifically the "Git workflow"—to scholarly writing. By integrating Markdown, GitHub-based version control, and automated citation management, Manubot enables large-scale, transparent collaboration. This paper describes the Manubot workflow and demonstrates its efficacy through the "Deep Review," a collaborative project involving dozens of authors.

Introduction

The conventional process of writing research papers is frequently a "black box." Small teams often rely on proprietary tools like Microsoft Word or offline LaTeX editors, which struggle with version control (e.g., manuscript_final_v2_revised.docx) and lack transparent contribution histories. These issues are exacerbated in large-scale collaborations where coordinating edits among dozens of authors becomes nearly impossible. Furthermore, static PDFs fail to link effectively to the underlying data and code, hindering the ideals of open science.

Methodology: Manuscripts as Code

Manubot treats a manuscript like a software project, employing a workflow engine with several key components:

  • Markdown Content: Manuscripts are written in plain-text Markdown, allowing Git to track changes line-by-line for easy review.
  • Git & GitHub: Utilizing a "fork-and-pull" model, contributors propose changes via Pull Requests, which are discussed and refined in public forums.
  • Continuous Integration (CI): Automated services like Travis CI "build" the manuscript upon every proposed change, catching formatting or citation errors before merging.
  • Citation by Identifier: Authors cite persistent identifiers (DOIs, PubMed IDs, etc.) directly in the text. Manubot automatically fetches metadata and formats the bibliography.
  • Blockchain Timestamping: Using the OpenTimestamps protocol, Manubot hashes the manuscript and stores it on the Bitcoin blockchain to provide verifiable proof of existence for any version.

Evaluation and Case Studies

The authors evaluated Manubot using real-world "stress tests" rather than traditional datasets:

  • The Deep Review: A massive collaborative review of deep learning in biology involving 36 authors from 20 institutions, serving as a primary case study for scalability.
  • Sci-Hub Coverage Study: A project demonstrating Manubot’s ability to handle rapid, transparent corrections following public peer review.
  • Rootstock: A template repository provided by the authors to help new users initialize their own Manubot projects.

Key Insights

The core innovation of Manubot is the realization that software engineering rigors—version control, automated testing, and modularity—are ideally suited for scientific authoring. This approach enables granular attribution, where Git commits provide a transparent record of exactly who contributed what, moving beyond the political nature of author order. Additionally, it facilitates the "living" paper, allowing for continuous updates and instant corrections while maintaining a clear version history.

Results

Manubot demonstrated significant scalability during the "Deep Review," successfully managing 755 commits and 317 pull requests from 36 authors. In the Sci-Hub study, the system allowed for rapid correction; an error identified via social media was "crossed out" using Markdown’s strikethrough and updated within hours, preserving the original error for transparency. The "citation by identifier" system also proved highly efficient, drastically reducing the manual labor associated with bibliography management.

Limitations and Future Work

Despite its advantages, Manubot has a technical barrier to entry, requiring familiarity with Git and Markdown. Archiving the rich discussions within GitHub Issues and Pull Requests remains a challenge, as these are not currently part of the versioned manuscript text. Future work aims to simplify the initial setup process and improve "preview" deployments to allow authors to view rendered versions of their work before merging changes.

Reference

Himmelstein DS, et al. (2019) Open collaborative writing with Manubot. PLoS Comput Biol 15(6): e1007128. https://doi.org/10.1371/journal.pcbi.1007128

Summary updated

Abstract

Open, collaborative research is a powerful paradigm that can immensely strengthen the scientific process by integrating broad and diverse expertise. However, traditional research and multi-author writing processes break down at scale. We present new software named Manubot, available at https://manubot.org, to address the challenges of open scholarly writing. Manubot adopts the contribution workflow used by many large-scale open source software projects to enable collaborative authoring of scholarly manuscripts. With Manubot, manuscripts are written in Markdown and stored in a Git repository to precisely track changes over time. By hosting manuscript repositories publicly, such as on GitHub, multiple authors can simultaneously propose and review changes. A cloud service automatically evaluates proposed changes to catch errors. Publication with Manubot is continuous: When a manuscript's source changes, the rendered outputs are rebuilt and republished to a web page. Manubot automates bibliographic tasks by implementing citation by identifier, where users cite persistent identifiers (e.g. DOIs, PubMed IDs, ISBNs, URLs), whose metadata is then retrieved and converted to a user-specified style. Manubot modernizes publishing to align with the ideals of open science by making it transparent, reproducible, immediate, versioned, collaborative, and free of charge.
BibTeX
@article{himmelstein2019open,
  author = {Daniel S. Himmelstein and Vincent Rubinetti and David R. Slochower and Dongbo Hu and Venkat S. Malladi and Casey S. Greene and Anthony Gitter},
  title = {{Open collaborative writing with Manubot}},
  journal = {PLOS Computational Biology},
  year = {2019},
  doi = {10.1371/journal.pcbi.1007128},
}
Figure