WorkingWiki

From Projects
Jump to: navigation, search

A short WorkingWiki demo video
WorkingWiki is a free software extension for MediaWiki to facilitate collaborative, reproducible open research. It makes a wiki into a powerful environment for collaborating on software, data processing, and publication-quality manuscripts.

The WorkingWiki extension allows you to store "source files" in your wiki and develop, test, run and publish them easily. Examples include a project of five LaTeX files and six EPS images that compile together into a single PDF file, or an R script that includes two other R source files and produces a CSV data file and several EPS figures. The WorkingWiki extension keeps track of when the source files have changed and when to redo the processing to update the output, and how to display the various file formats involved. The output files and images can be displayed in wiki pages along with the source code, and can be used as inputs to further computations.

  • Example: collaborating on a LaTeX document
It's very common for a group of scientific authors to write a paper by emailing each other copies of .tex files daily or hourly. This is inconvenient — in order to look at the paper you have to save the file into a directory and compile it — and unreliable — it's easy to get mixed up and lose someone's edits, or overwrite them with someone else's copy of the file. WorkingWiki is an elegant solution to these problems. Once the .tex files, .bib files, and images are in the wiki, it's easy for everyone to edit and see the updated results (as HTML and PDF versions of the compiled document), and the wiki keeps track of all the changes and their authors, and makes it easy to review or undo them. It also provides a convenient place to discuss changes, without having to put comments into the manuscript itself.
  • Example: collaborative, reproducible lab science
A research team can use WorkingWiki to archive experimental data (using the wiki's history features to record who uploaded which data files when); develop their data-processing scripts collaboratively in the wiki; construct the scripts that produce figures and tables in the wiki; create the manuscript that presents the results in the wiki; and finally export the manuscript both as a PDF and as a .tar.gz file ready to submit to a scientific journal. The data, source code, and manuscript can then be made available to the world as is. This process captures all the material needed to understand and reproduce the research project, with its revision history intact, and in a form that is easy to annotate and publish online. A research team developing simulation programs rather than using experimental data can use WorkingWiki in the same way.

WorkingWiki is developed principally for research groups, but is likely to have a variety of other uses as well.

WorkingWiki operates on source files that are stored in standard wiki pages. Source files are collected into projects. When an output file is called for, WorkingWiki does its work by invoking make to create or update the file from the source files in its project before displaying it. In this way, you can edit your code (or .tex documents, or data files, or whatever files) by editing the wiki, and run the code and view the output (the typeset version of your paper, the latest version of your figures, the textual output of your program) just by previewing or saving the page.

  • WorkingWiki provides some features of an integrated development environment:
    • You can edit source code in your favorite editor.
    • It coordinates compiling (if necessary) and running your code, and displaying the results.
  • WorkingWiki provides some features of a revision control system:
    • It uses MediaWiki's history features to record author, date/time, and content of every change to the files and the wiki pages they are connected to.
    • It allows you to export the source code to your workstation and work on it offline.
  • WorkingWiki's "project engine" provides a job management system on the server.
    • Relationships between source and product files are flexibly specified using makefiles.
    • Lengthy computations can be run as background jobs and integrated into the wiki's output when ready.
  • WorkingWiki integrates editing and running code with wiki editing.
    • It allows source and product files to be mixed freely into wiki pages' text.
    • Editing is fully collaborative.
    • The effects of changes to source files can be fully previewed before saving to the wiki.
    • The wiki is a simple, elegant way to present your work to the world.

McMaster wiki users: see also Getting Started on Lalashan Working Wikis.

Contents

Features

Screenshot of a WorkingWiki-enabled wiki page displaying part of a LaTeX document
  • WorkingWiki has special features for translating LaTeX documents to HTML, for display directly in the wiki page, including figures, citations and equations (using MathML and MathJax). WorkingWiki allows you to edit complete LaTeX documents collaboratively on the wiki, view the fully formatted document in the wiki page, and export the documents' source files or PDF output to your workstation when ready to submit or circulate.
  • Works with documents that involve multiple files, stored on one or many wiki pages. LaTeX \include, \bibliography, \includegraphics, and like commands are supported. Filenames do not need to match page names.
  • WorkingWiki is extensively customizable, supporting collaborative development and use of computer programs in any language. This server currently supports Perl, R, sed, awk, and maxima, and other combinations of languages can be installed by system administrators. Images and other files created by computer programs can be included directly in LaTeX documents and read by other programs, and are updated automatically when the programs or source data files are changed. The development environment can be customized by adding default make rules, and in many other ways.
  • WorkingWiki supports reproducible and open research by allowing researchers to collect all the files involved in a research project — data files, source code, documentation, publications — in an accessible place where collaborators can develop them together, and the public can view and download the entire project, to verify results and try their own experiments.
  • WorkingWiki has undergone extensive user testing. It has been in use on numerous wikis at McMaster University since 2008, with researchers in multiple labs relying on it for their daily work. While WorkingWiki is, of course, not free of bugs, including security issues — no software is — it is stable and reliable for serious use on closed lab wikis.

Documentation

Publications

Examples

Advanced Examples

Other Resources

This low-volume list is the best place to go for support, both for users and for wiki admins

short url for this page: http://tiny.cc/workingwiki