How-to-guide: Using the documentation guidelines

Quick start guide

These are the steps required to use the documentation guidelines templates to create documentation for a new, or existing (start at step 2), software project:

Important: Using the templates in this repository is not the only option! See this page for more details.

Fork the documentation guidelines repository in your account / organisation, or update an existing repository and cite the documentation guidelines.
Update the recommended metadata files.
Update the optional metadata files.
Tidy your repository.
Register your repository in a suitable place (e.g. Zenodo, WorkflowHub, bio.tools).

Done!

In-depth guide

Start with your README.md, which is the explainer file for your software or project.

You have two options for updating its contents depending on if you have cloned the documentation guidelines to create a new repository, or if you need to update an existing repository.

Creating a new repository

In this case:

Fork the template repository
Select a template from the documentation templates directory
Move the template file into the root directory of the repository,
Complete the necessary sections of the template,
Delete the other headings, and
When ready, delete the original README.md file from the template repository and rename your completed documentation as README.md.

Updating an existing repository

You can do two things here, either copy the contents of one of the template documentation files into your existing README.md file, or you can use existing resources like https://readme.so/ to create your own custom README content.

Important: In either case, make sure you cite the documentation guidelines repository, and any other resource(s) you used to create your project.

These are the current templates that are available in documentation_templates/:

tools.md: template for documenting software tools.
workflows.md: template for documenting computational workflows.
infrastructure_optimisation.md: template for documenting software optimisation required for specific compute infrastructures (cloud, HPC, other).
benchmarking.md: template for documenting benchmarking outcomes for software.

Update recommended files

The files that we recommend you always include are detailed below:

`LICENSE`

The license indicates if, and how, someone can reuse your software or project. You need to select a license (https://choosealicense.com/) and copy the license text into the LICENSE.md file.

`CHANGE_LOG.md`

A log of the changes made for each version / release. Make sure to update CHANGE_LOG.md when you make changes to your software or project.

`CITATION.cff`

A standard file type that indicates how someone should cite your software or project (Druskat 2021, Lee 2018).

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.
You can easily generate your own CITATION.cff using this resource https://citation-file-format.github.io/cff-initializer-javascript/#/

The documentation guidelines include a CITATION.cff file to highlight how the repository and its contents should be cited.

Below is an example of this file format being used by the Sydney Informatics Hub. The file is available here.

cff-version: 1.0.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: "Samaha"
    given-names: "Georgina"
    orcid: "https://orcid.org/0000-0003-0419-1476"
  - family-names: "Willet"
    given-names: "Cali"
    orcid: "https://orcid.org/0000-0001-8449-1502"
  - family-names: "Deshpande"
    given-names: "Nandan"
    orcid: "https://orcid.org/0000-0002-0324-8728"
  - family-names: "Chew"
    given-names: "Tracy"
    orcid: "https://orcid.org/0000-0001-9529-7705"
title: "GermlineShortV_biovalidation"
version: 1.0
doi: 10.48546/workflowhub.workflow.339.1
date-released: 2022-05-05
url: "https://github.com/Sydney-Informatics-Hub/GermlineShortV_biovalidation"

Update optional file(s)

There are other useful files that you can include in your repository. These are described in more detail here.

`codemeta.json`

This is a standard metadata file type from the CodeMeta Project.

You can easily generate your own codemeta.json using this resource: https://codemeta.github.io/create/

Keep it simple

Only add the directories and structures that are needed, and highlight the purpose of each one.

Ensure your documentation is straightforward and easy to understand.

Delete elements of the template that you do not need. 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.

Register your repository

Below are some suggestions for where to register, based on the type of software you have created.

Tools

Computational workflows

References

Druskat, Stephan, Spaaks, Jurriaan H., Chue Hong, Neil, Haines, Robert, Baker, James, Bliven, Spencer, Willighagen, Egon, Pérez-Suárez, David, & Konovalov, Alexander. (2021). Citation File Format (1.2.0). Zenodo. https://doi.org/10.5281/zenodo.5171937

Lee BD (2018) Ten simple rules for documenting scientific software. PLoS Comput Biol 14(12): e1006561. https://doi.org/10.1371/journal.pcbi.1006561