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