Skip to content

Commit e2d7caa

Browse files
supernordsupernord
committed
Update README.md
1 parent 24234be commit e2d7caa

File tree

1 file changed

+88
-18
lines changed

1 file changed

+88
-18
lines changed

‎README.md‎

Lines changed: 88 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,104 @@
1-
[tool / workflow name]
1+
Bioinformatics software documentation guidelines
22
==============
33

4-
> ## 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.
1111
- Typical files are included, such as a `LICENSE`, `CITATION.cff` and `change_log.md`
1212
- These guidelines will be further developed as needed to meet the requirements of the Australian BioCommons community.
1313

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
51+
52+
2. Create your own custom README content @ https://readme.so/
53+
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.
59+
60+
61+
### 2. Update the recommended files
62+
63+
The files that we recommend you always include are detailed below.
64+
65+
| File | Purpose | What you need to do! |
66+
|------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
67+
|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. |
70+
71+
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
1585

16-
# General recommendations for using [tool / workflow name]
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]
1789
18-
> Recommendations on using the workflow: for example, based on data set size, infrastructure suitability.
1990

20-
---
91+
## Contributing
2192

22-
# Resources available here
93+
Anyone is welcome to contribute to these documentation guidelines in the following ways:
2394

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:
95+
1. Create an issue, or
96+
2. Create a new branch of the repository and generate a pull request (PR)
2597

26-
- [system name](infrastructure_optimisation.md)
27-
- ...
98+
> If you have contributed, please also add your name to the section below!
2899
29-
---
30100

31-
# Attributions
101+
# Acknowledgements & attributions
32102

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

0 commit comments

Comments
 (0)