8 Documentation

Documentation serves as a bridge between the developer and user, and effectively communicating and explaining the code is as important as the code itself.

Often, two types of documentation are distinguished:

User documentation is aimed at those who will use the software, focusing on how to effectively utilize it. This documentation typically includes user manuals and tutorials, possibly FAQs and troubleshooting guides. The emphasis is on simplicity and accessibility, ensuring that anyone can understand how to use the software.
Developer documentation targets developers who need to understand the internal parts of the software for purposes of development, maintenance, or integration. It can include additional details such as Application Programming Interface (API) documentation and development guidelines. Developer documentation is more detailed providing insights necessary for modifying and enhancing the software.

8.1 How to write a good README

Although the specific content of a README can vary from project to project, several sections are recommended because they address fundamental aspects that are relevant to most projects.

You should ensure that your README addresses the following:

The purpose of the project is explained.
You have described how to install, use and develop the code.
You have explained the licensing terms for the project.
Information is provided on how to reach out to you, ask questions, or contribute.

8.1.1 Description

Although explaining the purpose might sound self-explanatory it is important to clearly explain the motivations and objectives of your project. This section should serve as an introductory overview that informs potential users and contributors about the essence of your project.

Provide background information and include links to any references that someone might not be familiar with. If there are alternatives to your project, this is the place to outline what sets your project apart.

8.1.2 Installation and usage

This section should detail the steps needed to set up the software in their environment.

Before installation, users must be aware of any prerequisites or dependencies required. This can include specific versions of programming languages, libraries, operating systems, and hardware. It is recommended to make use of a dependency manager such as pip or conda for easy and repoducible installation.

After listing the dependencies, describe the installation process step-by-step. This might involve downloading the software from a repository, compiling code, or using a package manager.

Example: The scikit-learn GitHub repository provides a good example of the Installation section of a README.

You can include the simplest possible usage example directly in the README and provide more complex examples in additional files or links.

Example: The TensorFlow GitHub repository gives a small usage sample after installation instructions and provides a link with additional examples and tutorials.

It is recommended to write READMEs in markdown formatting and they should be placed at the top level directory of your project. It is better that your README is on the side of too much information than too little. If you find your README is becoming too extensive, think about incorporating additional forms of documentation instead of omitting important details.

Further reading

8.1.3 CITATION

It’s straightforward to cite research papers, but with software sometimes it’s not as obvious. It is recommended to place a CITATION.cff file in the root of your repository to inform others about the preferred way to cite the software. GitHub can automatically parse the .cff file to create citation snippets in APA or BibTeX format. If you’d prefer the software to be cited through a journal publication, you can mention this in the README and in the CITATION.cff file.

An example of a CITATION.cff

cff-version: 1.2.0
message: "If you are using this software, please cite it as shown below."
authors:
- family-names: "Doe"
  given-names: "Jane"
  orcid: "https://orcid.org/9999-9999-9999-9999"
title: "Name of your software"
version: 1.0.1
doi: "11.1111/11111"
date-released: 2024-12-31
license: MIT
url: "https://github.com/your_repo"

How the citation would look on GitHub

On GitHub it will show in either APA or BibTeX formatting, as they are the currently supported formats. If you add a CITATION.cff file to your repository, then a label for citing will automatically be generated and will show up on the right sidebar of the repository.

APA

Doe, J. (2024). Name of your software (Version 1.0.1) [Computer software]. https://doi.org/11.1111/11111

BibTeX

@software{Joe_Name_of_your_software_2024, author = {Doe, Jane}, doi = {11.1111/11111}, month = {12}, title = {{Name of your software}}, url = {https://github.com/your_repo}, version = {1.0.1}, year = {2024} }

This is an example of software citation.

When citing a paper that is linked to the software you can use preferred-citation argument.

An example of a CITATION file citing a research article

cff-version: 1.2.0
message: "If you are using this software, please cite it as shown below."
authors:
- family-names: "Doe"
  given-names: "Jane"
  orcid: "https://orcid.org/9999-9999-9999-9999"
title: "Name of your software"
version: 1.0.1
doi: "11.1111/11111"
date-released: 2024-12-31
license: MIT
url: "https://github.com/your_repo"
preferred-citation:
    type: article
    authors:
    - family-names: "Doe"
      given-names: "Jane"
      orcid: "https://orcid.org/9999-9999-9999-9999"
    doi: "11.1111/11111"
    journal: "The title of the journal"
    month: 12
    start: 19 # the first page number
    end: 29 #the last page number
    title: "Name of your submitted paper"
    issue: 9
    volume: 2
    year: 2024

Similarly as above, GitHub will generate a citation in APA and BibTeX formats.

Further reading

CITATION.cff documentation
GitHub documentation on CITATION files - this resource also includes how to cite something other than software or a journal article.
Generate CITATION.cff files
Citation File Format GitHub

8.1.4 CONTRIBUTING guide

It is important to provide clear instructions on how developers and the user community can get involved in your project. Adding a CONTRIBUTING guide to your repository encourages external collaborations, sets expectations and establishes guidelines for contributions.

Setting up a CONTRIBUTING guide

There are no strict guidelines for a contributing guide and the content will depend you the project size, number of collaborators, and your particular workflow. Consider including:

Introduction: Welcome the contributors and express appreciation for community contributions.
Add a code of conduct: This helps to maintain a respectful and inclusive environment.
How to contribute: Explain precise contribution guidelines
- Issue Tracking: Explain how to report issues (bugs, feature requests, etc.).
- Pull requests: Detail the process for submitting pull requests. This includes instructions on forking the repository, creating a branch, making changes, and the follow-up steps for a successful pull request.
- Code review process: Describe how contributions will be reviewed and integrated.
Community and communication: List the channels through which contributors can communicate and set their expectations regarding the responsiveness and availability of project maintainers.
Style guide and coding standards: Providing a (separate) coding style guide or documenting coding standards would be best practice. This way contributors would ensure consistency across the codebase.
Legal implications: Inform contributors about the licensing under which their contributions will be used and any intellectual property considerations they should be aware of.