Documentation

Resources

• FIT: Code Documentation
• FIMS Developers Guide

Tools

Readme

Readme.md is shown at the bottom of a GitHub repo and can be minimal or complex. Note, for an organization you should give some thought to standardizing the content of your Readme’s and including a disclaimer at the bottom. See the Fisheries Integrated Toolbox example.

• EPA CMAQ repo Links to documentation, DOIs, past releases, installation instructions for EPA’s CMAQ modeling system.
• CISA Sparrow repo
• USGS PEST++
• Here is a Python example from USGS geomag-algorithms and groundmotion-processing
• [NPS acoustics])https://github.com/nationalparkservice/acoustic_discovery) example with lots of images.

GitHub wiki

• EPA API tool, EPA useeior package.
• College scorecard

pkgdown

If you are preparing an R package, then the pkgdown R package is the way that people make websites directly from their R package documentation. The Fisheries Integrated Toolbox has a NMFS branded pkgdown template that you can use. It’ll add all the NOAA Fisheries branding and colors. pkgdown Template. There are many examples of pkgdown sites on GitHub. The key file to change is pkgdown/_pkgdown.yml and I find it easiest to poke around GitHub and find version of that file to copy and modify.

bookdown

bookdown is also very popular for making documentation and RStudio makes it easy to build books. Here is an example of one of my bookdown books. Here is a bookdown lab manual written by one of the first Openscapes cohort teams as their team project: Fay Lab Manual. A bookdown book is just a collection of Rmarkdown files. You write those and bookdown makes it into the online book, which you can put on GitHub Pages.

Other

Another common way to include documentation is a folder with the documentation (in whatever format you want) with links to that from the Readme file or GitHub Pages.

• EPA CMAQ repo has a folder called DOCS in the repo which holds documentation in markdown format, .md. The Readme points to those files and because they are markdown, you see them as formatted (not raw) text.
• USGS shakemap created a webpage which is kept in the docs folder. GitHub Pages then points to that folder.
• Sphinx documentation is used by Python users and is a bit like bookdown in appearance but uses a different markup language (rst). Here are examples from USGS geobipy and gmprocess. The html output is put in the docs folder and GitHub Pages is pointed to that.
• Quarto documentation allows both Jupyter and Rmd files. NASA Openscapes is using this for their hackathon documentation.