A Collaborative Web-Based Vision for STScI Documentation

Introduction

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.

Relevent Technologies

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.