How-to use the documentation guidelines

Why do the documentation guidelines exist?

Do you want your tools and workflows to be documented in a standard way?

If the answer is yes, then read on!

The Australian BioCommons has been working with community bioinformaticians and our infrastructure partners to establish a guidelines repository that can act as a template for documentation of tools and workflows.

The repository aims to provide guidance and a minimal starting template for:

• Documenting a new tool or workflow
• Documenting tool or workflow access, use and optimisation on infrastructures
• Recommending additional repository contents that make your work more FAIR

Reusing the guidelines?

These guidelines are intended to be reused. If you do reuse the guidelines, please fork the template repository and acknowledge its value by including the following citation.

Gustafsson, J., Davis, B., de la Pierre, M., Stott, A., Beecroft, S., Downton, M., Edwards, R., Chew, T., Samaha, G., & Al Bkhetan, Z. (2023). Australian BioCommons Documentation Guidelines (Version 1.5.0) [Computer software]

The services available to researchers through the Australian BioCommons are subsidised by NCRIS as part of the national strategy to make research infrastructure accessible and affordable. Acknowledgements are evidence that investments in equipment and people have led to important outcomes, which in turn builds the case for future investments.

Contributors

The BioCommons would like to acknowledge the contributions of the following individuals and institutions to the documentation guidelines:

Acknowledgements

The Australian BioCommons guidelines are based on learnings from existing efforts, including our own projects, but also the Galaxy, Nextflow and Snakemake communities.

The documentation guidelines template repository is supported by the Australian BioCommons via Bioplatforms Australia funding, the Australian Research Data Commons (https://doi.org/10.47486/PL105) and the Queensland Government RICF programme. Bioplatforms Australia and the Australian Research Data Commons are enabled by the National Collaborative Research Infrastructure Strategy (NCRIS).

This guide makes use of the ELIXIR toolkit theme

References

• Druskat, S., Spaaks, J. H., Chue Hong, N., Haines, R., Baker, J., Bliven, S., Willighagen, E., Pérez-Suárez, D., & Konovalov, O. (2021). Citation File Format (Version 1.2.0) [Computer software]. https://doi.org/10.5281/zenodo.5171937
• Spaaks, J. H., Verhoeven, S., Diblen, F., Druskat, S., Soares Siqueira, A., Garcia Gonzalez, J., & Cushing, R. (2023). cffinit (Version 2.3.1) [Computer software]. https://github.com/citation-file-format/cff-initializer-javascript
• Carole Goble, Stian Soiland-Reyes, Finn Bacall, Stuart Owen, Alan Williams, Ignacio Eguinoa, Bert Droesbeke, Simone Leo, Luca Pireddu, Laura Rodríguez-Navas, José Mª Fernández, Salvador Capella-Gutierrez, Hervé Ménager, Björn Grüning, Beatriz Serrano-Solano, Philip Ewels, & Frederik Coppens. (2021). Implementing FAIR Digital Objects in the EOSC-Life Workflow Collaboratory. Zenodo. https://doi.org/10.5281/zenodo.4605654
• Jon Ison and others, Tools and data services registry: a community effort to document bioinformatics resources, Nucleic Acids Research, Volume 44, Issue D1, 4 January 2016, Pages D38–D47, https://doi.org/10.1093/nar/gkv1116
• Matthew B. Jones, Carl Boettiger, Abby Cabunoc Mayes, Arfon Smith, Peter Slaughter, Kyle Niemeyer, Yolanda Gil, Martin Fenner, Krzysztof Nowak, Mark Hahnel, Luke Coy, Alice Allen, Mercè Crosas, Ashley Sands, Neil Chue Hong, Patricia Cruse, Daniel S. Katz, Carole Goble. 2017. CodeMeta: an exchange schema for software metadata. Version 2.0. KNB Data Repository. doi:10.5063/schema/codemeta-2.0
• O’Connor BD, Yuen D, Chung V et al. The Dockstore: enabling modular, community-focused sharing of Docker-based genomics tools and workflows [version 1; peer review: 2 approved]. F1000Research 2017, 6:52 (https://doi.org/10.12688/f1000research.10137.1)

Affiliations