A Collaborative Web-Based Vision for STScI Documentation
The preparations for the launch of JWST offer an opportunity for STScI to take advantage of emerging technologies to create a written communication output on-par with its scientific output. The Free Open Source Software (FOSS) community has had similiar requirements as STScI to create extensive technical documentation. These FOSS projects, including the partially STScI-funded Astropy software package, including dozens of geographically seperated authors with a rapid document release cycle. This document outlines the underlying technologies used by Astropy and other software projects and explores various implementations that STScI could use to produce user information of similar quality.
The modern web is full of powerful tools that were once restricted to local processes. Advances in web technology have made online collaboration the norm from Google Docs to Facebook. These are often distinct from their predecessors in that they and truly web-based, not just web-enhanced; everything happens in the browser. This software model, called Software as a Service (SaaS) as opposed to the more traditional Software as a Product (SaaP) offers a lightweight and rapidly evolving ecosystem.
I’ve chosen both of these platforms because I feel they both address core requirements for successful documentation.
Vetting: There has to be that ability to implement a workflow where the changes to final version are carefully vetted but also allows new users to submit changes without fear of breaking the final product.
History: There has to be a single authoritative timeline of changes to the document with the ability to revert to any point in that history. Collaboration: Multiple authors have to be able to seamlessly and transparently integrated.
Singularity: There has to be a single authoritative version of the document to avoid the “endless filename” problem (http://www.phdcomics.com/comics/archive.php?comicid=1531)
Standard Formatting: The text of each document should be available in a standard, non-proprietary plain text formats such as HTML5, Markdown, LaTeX. This decouples the data from the platform used to create it and facilitates translation between formats.
Authorea is a web-based software as a service (SaaS) platform for collaborative document creation that supports multiple input and output formats. Built by CfA astronomers using established open source technologies and boasting recent successes such as a 200+ author CERN paper, Authorea provides a model for how STScI content could be handled in the JWST era.
Authorea provides a web interface for multiple users to collaborate on documents. All document changes are recorded using the git version control system. The text can be written in either LaTeX or Markdown markup languages. A variety of different outputs are possible as well as document formats for science journals and research proposals including HST.
Authorea was built by CfA astronomers, its leadership team of 6 includes 2 astronomy post-docs and a Harvard Astronomer: Eli Bressert, Alberto Pepe, and Alyssa Goodman. The CfA/SOA has a history of producing technology successfully adopted by STScI going back to DS9 and continuing with OED employing XXX to develop XXX.
Git is a popular, modern version control system used by software developers to track and manage line-by-line changes to software. This same system, with all its organizational advantages, is leveraged in a transparent manner by Authorea. It allows power users to access to full functionality of version control with git while remaining transparent to average users.
Authorea supports both Markdown, an extremely simple markup language, and LaTeX, a more robust markup language and one that is familiar to astronomers. Since LaTeX is the lingua franca of science publication it will allow the science staff and the astronomy community to leverage their existing document creation skills. The Markdown format is an accessible alternative.
Because LaTeX/Markdown are both standardized markup languages they support translation into other formats such as HTML5, PDF, plain text, and ePub. Beyond just output medium, Authoria can provide format templates, and already does so for HST proposals. This feature could be extended to include JWST proposals, TIRs, ISRs, and even IHBs.
If Authorea were to disappear tomorrow we would still retain all the information and the change sets. Because Authorea uses standard technologies, STScI retains absolute freedom with its data. At anytime the full dataset along with a full history of retrievable changes can be downloaded in a standard text format. This provides STScI the flexibility to change documentation methods in the future as well as build their own tools around these normalized formats.
GitLab is an open-source clone for the popular GitHub collabroative version control platform. GitLab provides several useful features for for software development teams including a issue tracking system and wiki pages. The WFC3 team at STScI maintains a XXX word documentation wiki on the institutes internal GitLab instance. While this wiki system is an idea solution for future STScI documentation it does provide several diserable features and illustrate the type of powerful organic collaboration that can happen when there is a low barrier to entry for document creation and maintainence.