Research Guides: Research Software: Designing for Publication and Reproducibility: Documentation

Documentation

This image was created by Scriberia for The Turing Way community and is used under a CC-BY licence. DOI 10.5281/zenodo.3332807.

Colleagues in your research group, reviewers, and scholarly peers will all need to know how to use your code. Another huge incentive to document your code is that, between teaching, learning, shifting your focus from one project to another, and other distractions of living life and existing in academia, you may need some reminders yourself. As the data scientist Garret Christensen advises in a piece in the edited volume The Practice of Reproducible Research:

"Comment the hell out of your code so you know what you were doing when a journal makes a decision about your submission after six months."

Below, we suggest a few methods for documentation. The level of documentation your project requires may vary. For a simple script that produces figures for a paper that you or a reviewer may wish to validate, you need to provide installation instructions, but you probably don't need to create a full-on tutorial. For a more complex project, making a Jupyter Notebook or R Notebook that combines code with notes and observations might be helpful.

Documentation Best Practices

Load dependencies at the top of the program. This will help a user find, load, and troubleshoot other programs they need to run your code.
Name variables consistently for easier troubleshooting and to make the code more (human-)readable.
Comment out distinct modules and functions to clarify the purpose they serve within the code.
Within your code, add comments on their own line, not inline with commands.
Document expected inputs and outputs--what kind of argument the program and its components expect, and what it will display or produce to indicate it has run successfully.

Resources

How to Write Good Documentation
LibGuide from UC Berkeley about good documentation for research software

Tools For Documentation From Source Code

Sphinx
Sphinx is a tool designed for for creating documentation in Python that can be used for other languages as well. It uses reStructuredText and outputs to a variety of formats, including HTML and PDF.
Sphinx Gallery
Sphinx Gallery will take Python code, run it, and render the results as HTML. If your code creates visualizations, this is a helpful way to display results in your documentation.
Readthedocs
Readthedocs hosts documentation written in reST. You can connect it almost seamlessly to Sphinx documentation for public web presentation. It also can be set up to be versioned update every time you update a GitHub, GitLab, or BitBucket repo.
Diátaxis
A framework for designing documentation, with tips for how to structure documentation depending on its intended purpose and audience.
Doxygen
Doxygen is another, older documentation generator, primarily designed for C++. Some users find it more difficult to use than Sphinx but more robust, especially for code that is not written in Python.

Software-Specific Styling and Commenting Guidelines

R

Stata

Coding Style Guide (PDF)
by the Harvard Strategic Data Project
Stata for Researchers
by the University of Wisconsin Social Science Computing Cooperative

Research Software: Designing for Publication and Reproducibility

Documentation

Documentation Best Practices

Resources

Tools For Documentation From Source Code

Software-Specific Styling and Commenting Guidelines

R

Stata

MATLAB

SAS

SPSS

Python