Bioinformatics software documentation guidelines

Description

This repository allows anyone to create simple boilerplate documentation for any bioinformatics software, using guidelines that have been co-created by the Australian BioCommons and members of the community.

• This template repository contains a set of guidelines for documenting bioinformatics software (e.g. tools and workflows).
• The initial guideline version uploaded to GitHub was informed by current documentation practices and structures used in the GitHub community.
• Subsequent versions have been modified and updated with input from Australian BioCommons engagements with infrastructure partners and the bioinformatics community.
• Typical files are included, such as a LICENSE, CITATION.cff and change_log.md
• These guidelines will be further developed as needed to meet the requirements of the Australian BioCommons community.

You can use this repository as:

1. A base template for a new GitHub repository.
2. A source of templates or ideas that you can use in your existing repositories.

Quick start guide

1. Fork the template to reuse it for a new repository
2. Replace the README.md with one of the files available in the documentation_templates directory, or create your own custom README here: https://readme.so/
3. Update the recommended files, if the required information is available (LICENSE, CHANGE_LOG and CITATION.CFF)
4. Update, or delete, the optional files (i.e. codemeta.json)
5. Delete elements you do not require (documentation_templates directory, original README.md)

See the How-to Guide for detailed instructions

Citing this repository

If you use this template repository, or any of its documentation elements, please use 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]

Contributing

Anyone is welcome to contribute to these documentation guidelines in the following ways:

1. Create an issue, or
2. Create a new branch of the repository and generate a pull request (PR)

If you have contributed, please also add your name to the section below!

Acknowledgements & attributions

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).

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

• Johan Gustafsson (Australian BioCommons, University of Melbourne) @supernord
• Brian Davis (National Computational Infrastructure) @Davisclan
• Marco de la Pierre (Pawsey Supercomputing Centre) @marcodelapierre
• Audrey Stott (Pawsey Supercomputing Centre) @audreystott
• Sarah Beecroft (Pawsey Supercomputing Centre) @SarahBeecroft
• Matthew Downton (National Computational Infrastructure) @mattdton
• Richard Edwards (University of New South Wales) @cabbagesofdoom
• Tracy Chew (University of Sydney) @tracychew
• Georgina Samaha (University of Sydney) @georgiesamaha
• Ziad Al Bkhetan (Australian BioCommons, University of Melbourne) @ziadbkh

Citations

• 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)