You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the change log for the documentation guidelines template.
5
+
To start writing a change log for your own software, copy the structure below.
6
+
7
+
```
8
+
## version number
9
+
10
+
Details of the changes made since the last version
11
+
```
12
+
13
+
# Documentation guidelines change log
14
+
15
+
16
+
## v1.5
17
+
18
+
- Created `documentation_templates` directory
19
+
- Added more instructions to individual files (`CITATION.cff`, `licence` etc.)
20
+
- When using the guidelines as a template, the `README.md` should now be deleted when ready, and a replacement selected from the `documentation_templates` repository.
21
+
- Add example `codemeta.json`
22
+
23
+
24
+
## v1.4 (first official release)
25
+
Many thanks to @georgiesamaha and @tracychew from the Sydney Informatics Hub (University of Sydney) for the idea to add `*.cff` files to the guidelines.
26
+
- added both blank and documentation guideline `*.cff` files
27
+
-`tools.md` was updated to align with `workflows.md` structure from v1.3
### You can create your own using the blank template provided at the bottom of this file"
6
+
### Simply remove the "#" and complete each field provided: for more information please see 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
7
+
1
8
cff-version: 0.0.1
2
9
message: "If you use these documentation guidelines, please cite as below."
> ## Delete this section when the first version of the documentation is complete
5
-
> You can make use of this template repository as a base template for a new GitHub repository.
6
-
>
7
-
> **General information about the guidelines**
8
-
- This **template** repository contains a set of guidelines for documenting bioinformatics tools and workflows.
9
-
-There is a How-to-Guide to using this repository available here: https://australianbiocommons.github.io/how-to-guides/documentation/DocumentationGuidelines
10
-
-The initial version uploaded to GitHub was informed by current documentation practices and structures used in the GitHub community.
4
+
## Description
5
+
6
+
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.
7
+
8
+
- This template repository contains a set of guidelines for documenting bioinformatics software (e.g. tools and workflows).
9
+
-The initial guideline version uploaded to GitHub was informed by current documentation practices and structures used in the GitHub community.
10
+
-Subsequent versions have been modified and updated with input from Australian BioCommons engagements with infrastructure partners and the bioinformatics community.
11
11
- Typical files are included, such as a `LICENSE`, `CITATION.cff` and `change_log.md`
12
12
- These guidelines will be further developed as needed to meet the requirements of the Australian BioCommons community.
13
13
14
-
---
14
+
You can use this repository as:
15
+
16
+
1. A **base template** for a new GitHub repository.
17
+
2. A **source of templates or ideas** that you can use in your existing repositories.
18
+
19
+
> **If you use these guidelines, please cite this work :)**
20
+
>
21
+
> Gustafsson, J., Davis, B., de la Pierre, M., Stott, A., Beecroft, S., Downton, M., Edwards, R., Chew, T., & Samaha, G. (2023). Australian BioCommons Documentation Guidelines (Version 1.5.0) [Computer software]
22
+
23
+
24
+
## Quick start guide (using repository as a template)
25
+
26
+
1. Clone repository and use it as a template for a new repository
27
+
2. Replace `README.md` with one of the files available in the `documentation_templates` directory, or create your own custom README here: https://readme.so/
28
+
3. Update the recommended files, if the required information is available (`LICENSE`, `CHANGE_LOG` and `CITATION.CFF`)
29
+
4. Update, or delete, the optional files (i.e. `codemeta.json`)
30
+
5. Delete elements you do not require (`documentation_templates` directory, original `README.md`)
31
+
32
+
33
+
## Usage guide
34
+
35
+
When your documentation is ready, this README file should be deleted and replaced with either:
36
+
- A suitable template from the `documentation_templates/` directory, or
37
+
- A custom `README`. You can create custom content easily @ https://readme.so/.
38
+
39
+
40
+
### 1. Replace the repository `README.md`
41
+
42
+
A README.md is the explainer file for your software or project.
43
+
44
+
If you have cloned / copied this repository, you need to replace this README with either:
45
+
46
+
1. One of the templates from the `documentation templates` directory:
47
+
1. Rename the template documentation file to `README.md`,
48
+
2. Move the file into the root directory of the repository,
49
+
3. Complete the necessary sections of the template, and
50
+
4. Delete the other headings
15
51
16
-
# General recommendations for using [tool / workflow name]
52
+
2. Create your own custom README content @ https://readme.so/
17
53
18
-
> Recommendations on using the workflow: for example, based on data set size, infrastructure suitability.
54
+
These are the current templates that are available in `documentation_templates/`:
55
+
-`tools.md`: template for documenting software tools.
56
+
-`workflows.md`: template for documenting computational workflows.
57
+
-`infrastructure_optimisation.md`: template for documenting software optimisation required for specific compute infrastructures (cloud, HPC, other).
58
+
-`benchmarking.md`: template for documenting benchmarking outcomes for software.
19
59
20
-
---
21
60
22
-
#Resources available here
61
+
### 2. Update the recommended files
23
62
24
-
This repository contains structured documentation for ```[workflow name]```, including links to existing repositories and community resources, as well as a description of the optimisations achieved on the following compute systems:
63
+
The files that we recommend you always include are detailed below.
|LICENSE.md| The license that indicates how someone can reuse your software or project. | Select a license (https://choosealicense.com/) and copy the license text into this file. |
68
+
|CHANGE_LOG.md| A log of the changes made for each version / release. | Update this file when you make changes to your software or project. |
69
+
|CITATION.cff| A standard file type that indicates how someone should cite your software or project. | Update this file with the citation metadata for your software or project. GitHub will auto-detect this file and create a citation export option for you. |
28
70
29
-
---
30
71
31
-
# Attributions
72
+
### 3. Update the optional but useful file(s)
73
+
74
+
This folder contains useful files that you can include in your repository.
75
+
76
+
`codemeta.json`: this is a standard metadata file type from the [CodeMeta Project](https://codemeta.github.io/). You can easily generate your own `codemeta.json` using this resource https://codemeta.github.io/create/
77
+
78
+
79
+
### 4. Delete files and directories you do not need
80
+
81
+
These are guidelines only, and that means you can modify, update or delete elements of the file and directory structure to suit your specific use case.
82
+
83
+
84
+
## Citing this repository
85
+
86
+
> If you use this template repository, or any of its documentation elements, please use the following citation:
87
+
>
88
+
> Gustafsson, J., Davis, B., de la Pierre, M., Stott, A., Beecroft, S., Downton, M., Edwards, R., Chew, T., & Samaha, G. (2023). Australian BioCommons Documentation Guidelines (Version 1.5.0) [Computer software]
89
+
90
+
91
+
## Contributing
92
+
93
+
Anyone is welcome to contribute to these documentation guidelines in the following ways:
94
+
95
+
1. Create an issue, or
96
+
2. Create a new branch of the repository and generate a pull request (PR)
97
+
98
+
> If you have contributed, please also add your name to the section below!
99
+
100
+
101
+
# Acknowledgements & attributions
32
102
33
103
The guideline template 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).
34
104
@@ -45,4 +115,10 @@ The BioCommons would also like to acknowledge the contributions of the following
45
115
- Georgina Samaha (University of Sydney) [@georgiesamaha](https://github.com/georgiesamaha)
46
116
47
117
118
+
# Citations
119
+
120
+
- 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
121
+
- 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
122
+
- 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
123
+
- 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
0 commit comments