Intended Audience
- RC - Tool Developers
- RC - Website/Documentation Contributors
Consistent documentation is fundamental to the riverscapes consortium philosophy. In practical terms this minimally involves the following types of documentation:
- Source code documentation explaining the various components of a tool and how they work
- Tool web sites for end users to discover, download and run the tools
- Riverscapes Projects metadata to accompany the outputs of each tool
The above resources are intended as a reference and guide for RC developers and website contributors.
Best Practice Examples
BRAT - A New Research-Grade Script
In the case of tools or models that represent novel, new and/or significant methodological advances or scientific contributions, the model should also be vetted in the peer-reviewed scholarly literature. For example, the RC BRAT (Beaver Restoration Assessment Tool) beaver dam capacity model (BRAT) was originally vetted in:
- Macfarlane W.W. , Wheaton J.M., Bouwes N., Jensen M., Gilbert J.T., Hough-Snee N., and Shivick J. 2015. Modeling the capacity of riverscapes to support beaver dams. Geomorphology. DOI: 10.1016/j.geomorph.2015.11.019.
However, BRAT’s
- Source code documentation is in its open-source Riverscapes GitHub repo in the Riverscapes: https://github.com/Riverscapes/pyBRAT/
- The tool website at https://brat.riverscapes.net has all the end-user tool documentaoin
- Examples of BRAT data are available in Riverscapes Warehouses from https://brat.riverscapes.net/BRATData
Tributary Impact - Implementing a Research Grade Script
By contrast, agorithms and methods that have already been published and vetted, but are simply packaged into an opensource tool for others to use should cite the original author
For example, the Tributary Impact was originally vetted and presented in:
- Rice SP. 2017. Tributary connectivity, confluence aggradation and network biodiversity. Geomorphology 277 : 6–16. DOI: 10.1016/j.geomorph.2016.03.027
However, the algorithm was coded up to implement and shared as
- Source code documentation is in its open-source Riverscapes GitHub repo in the Riverscapes: https://github.com/Riverscapes/TributaryImpact
- The tool website at http://tributaryimpact.riverscapes.net/ and is minimally documented for transparency