# Documentation

[TOC]

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.

:::success
**Checklist**
*User documentation*
- [ ] README
- [ ] CITATION
- [ ] LICENSE

*Developer documentation*
- [ ] Code comments
- [ ] Contributing guidelines
- [ ] API documentation (docstrings)
- [ ] Optional: Code of conduct
:::

## 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:
1. The purpose of the project is explained.
2. You have described how to install, use and develop the code.
3. You have explained the licensing terms for the project.
4. Information is provided on how to reach out to you, ask questions, or contribute.

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

#### 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](https://github.com/scikit-learn/scikit-learn?tab=readme-ov-file#installation) 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](https://github.com/tensorflow/tensorflow?tab=readme-ov-file#install) 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](https://www.makeareadme.com/#more-documentation) instead of omitting important details.

:::success
:book: **Further reading**
- [Make a README - README 101](https://www.makeareadme.com)
- [Making READMEs readable](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md)
:::

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

::: info
:::spoiler 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"

:::

::: info
::: spoiler 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.
:::info
:::spoiler 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.
:::

:::success
:books: **Further reading**
- [CITATION.cff documentation](https://citation-file-format.github.io)
- [GitHub documentation on CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) - this resource also includes how to cite something other than software or a journal article.
- [Generate CITATION.cff files](https://citation-file-format.github.io/cff-initializer-javascript/#/)
- [Citation File Format GitHub](https://github.com/citation-file-format/citation-file-format)
:::

## LICENSES

:::warning
:warning: **Important**
- If no license file is provided with the software, the software is considered propriatary and cannot be used by others without written permission.
- For questions about data and software licenses, please consult your Faculty Data Steward.
:::

### TU Delft licensing policy
TU Delft by default holds the rights to the software created by its employees. In order to apply a pre-approved open source license, you have to follow the guidelines in [**TU Delft Guidelines on Research Software: Licensing, Registration and Commercialisation**](https://zenodo.org/records/4629635). It states:

> It is important to remember that in principle TU Delft holds the rights to the software created by its employees (i.e. software developers, researchers and/or staff). So, some formal (legal) steps are needed to arrange matters properly.

When these guidelines are followed and when the software is published, **TU Delft disclaims its copyright**, allowing software developers, researchers and staff to hold the copyright to their software and thereby having **the right to apply one of the pre-approved licences** when sharing software. The pre-approved open source software licences at TU Delft are Apache, MIT, BSD, EUPL, AGPL, LGPL, GPL, and CC0.

**Steps:**
1. Determine if it is possible to apply an Open Source Software licence to your project (see diagram below).
2. The waiver of TU Delft should be indicated in the software licence with the following text:
*Technische Universiteit Delft hereby disclaims all copyright interest in the program “Name program” (one line description of the content or function) written by the Author(s).
[Name Dean], Dean of [Name Faculty]*
3. Assert your own, personal copyright (© YEAR, [NAME], [REFERENCE project, grant or study if desired]. The reason for waiving the copyright and having the software developers, researchers and staff file the copyright in their own name facilitates the use of copyleft licences
4. Apply one of the TU Delft pre-approved Open Source Software licences in the format and form described in the licence text after stating, “This work is licensed under a [NAME and VERSION] OSS licence”.
5. Make the software openly available (for instance in an online repository such as GitHub).
6. Please consider acknowledging support from TU Delft and/or your funding provider.
7. Register the software either in 4TU.ResearchData or in PURE.

:::warning
:warning: *Please note that if the software is not published, and/or if the guidelines have not been followed correctly and/or if the software is not registered in PURE, then this ‘agreement’ is invalid and the software automatically falls under the legal copyright of TU Delft. This instantly nullifies the right of the software developer or researcher to apply for a licence and thus the open source software licence applied never came into existence. This works retroactively.*
:::

### Decision tree for applying for a license

TU Delft staff members can apply for an open source license according to the decision tree found in [TU Delft Guidelines on Research Software: Licensing, Registration and Commercialisation](https://zenodo.org/records/4629635).

<span style="font-size: 10px;">
Figure 1. Decision tree to guide software developers, researchers and staff on when they can apply an open source licence to their software (OSS: Open Source Software, IDF: Invention Disclosure Form). From: Bazuine, M. (2021). TU Delft Guidelines on Research Software: Licensing, Registration and Commercialisation. Zenodo. https://doi.org/10.5281/zenodo.4629635
</span>

### Types of open source licenses

- **Permissive licenses aka copyright (e.g., MIT, BSD, Apache):** These licenses allow users to do almost anything with the code, including using it in proprietary software.
- **Restrictive licenses aka copyleft (e.g., GPL, AGPL, LGPL, EUPL):** These licenses require any derivative works to be open source and distributed under the same license.

### Copyright licenses

1. **MIT:** Very simple and permissive, allowing almost unrestricted reuse. The software can be freely used, modified, ditributed, and sublicensed.
2. **BSD:** Similar to the MIT license, but it may include additional attribution requirements.
:::spoiler BSD license details
- ***Attribution:*** Requires that the copyright notice and list of conditions be included in all copies or substantial portions of the software (except for the BSD 0-Clause License, which does not require any attribution). There are different clause variants of the license. For example, a BSD 3-Clause license adds a clause preventing the use of the names of the project or its contributors to endorse or promote derived products without written permission.
- ***Patent Protection:*** Does not include explicit provisions for patent protection.
:::
4. **Apache:** Allows for the use, modification, distribution, and sublicensing of the software under certain conditions. It is often used in open source projects and is often the choice for its balance between permissiveness and the protection of patents. The Innovation and Impact Center recommends this license for industry collaborations.
:::spoiler Apache license details
- ***Attribution:*** Requires preservation of the original copyright notice and a notice of any modifications made.
- ***Patent Protection:*** Includes a patent retaliation clause, which provides an additional layer of protection. This clause terminates the license if the user initiates patent litigation against any entity regarding the licensed software.
- ***Notice Requirement:*** Modifications to the original code must be documented, and a NOTICE file must be included with any substantial portions of the software.
:::

:::spoiler :bulb: **Key differences between a BSD and Apache license**
- The Apache license includes a patent retaliation clause to protect against patent litigation, but the BSD license does not explicitly address patent rights.
- The BSD license does not require a specific notice file for modifications, but the Apache License requires a NOTICE file that documents any modifications made to the original code.
:::

### Copyleft licenses
1. **GPL (GNU General Public License):** One of the most widespread copyleft licenses. With the GPL license, any derivative work under this license automatically becomes subject to the same GPL terms, regardless of the size of the contribution. All future modifications and adaptions of code under this license is only compatible with this license and cannot be used in proprietary software.
3. **Derivatives from GPL (AGPL, LGPL, EUPL)**: From these the EUPL license is somewhat more flexible compared to others as it can coexist with other open source software licenses such as MIT, BSD, and Apache. For instance, if you integrate a portion of software that is licensed under Apache into a project governed by EUPL, that portion can retain its Apache license. In contrast, under the GPL, the entire codebase would need to be licensed under GPL.

:::info
:notebook_with_decorative_cover: Note: There are even instances when GPL licenses are incompatible with each other. For example, GPL-2.0 is incompatible with GPL-3.0. If a project uses GPL-2.0 you are essentially forced to use that license.
:::

### License compatibility

<span style="font-size: 10px;">
Figure 2. Compatibility of licenses. From: Bazuine, M. (2021). TU Delft Guidelines on Research Software: Licensing, Registration and Commercialisation. Zenodo. https://doi.org/10.5281/zenodo.4629635
</span>

:::info
:bulb: Don't forget to check whether your software's dependencies have restrictions on re-use.
:::

It is advisible to contact your faculty's data steward regarding licensing questions. If your project involves complex legal considerations, particularly regarding intellectual property rights or compliance with licensing agreements, the Innovation and Impact Center should also be involved.

:::success
:bulb: **Further reading**

- [TU Delft Research Software Policy](https://doi.org/10.5281/zenodo.4629662)
- [TU Delft Guidelines on Research Software](https://zenodo.org/records/4629635) - the TU Delft Research Software Policy approved by the Executive Board
- [Choose a license](https://choosealicense.com) - a simplified guide on choosing an open source license
- [tl;drLegal](https://www.tldrlegal.com) - Plain English summaries of software licenses
- [The Turing Way - Licensing](https://the-turing-way.netlify.app/reproducible-research/licensing)
:::

## 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:

1. **Introduction**: Welcome the contributors and express appreciation for community contributions.
2. **Add a [code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project):**: This helps to maintain a respectful and inclusive environment.
3. **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.
4. **Community and communication**: List the channels through which contributors can communicate and set their expectations regarding the responsiveness and availability of project maintainers.
5. **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.
6. **Legal implications**: Inform contributors about the licensing under which their contributions will be used and any intellectual property considerations they should be aware of.

:::success
:books: Further reading

- [GitHub's guide to setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
- [GitHub's own CONTRIBUTING guide](https://github.com/github/docs/blob/8ef6dfa3a1400156aee603c7642485ebba2161b8/.github/CONTRIBUTING.md)
- [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)

:::

A well-maintained `README` offers a snapshot of your project's current state, while a `CONTRIBUTING` guide promotes user/developer involvement. Together, these documents help maintain project clarity and ensure that contributions are managed efficiently.

## Resources

:::spoiler References used in this guide
- [scikit-learn GitHub repository](https://github.com/scikit-learn/scikit-learn?tab=readme-ov-file#installation)
- [TensorFlow GitHub repository](https://github.com/tensorflow/tensorflow?tab=readme-ov-file#install)
- [additional forms of documentation](https://www.makeareadme.com/#more-documentation)
- [Make a README - README 101](https://www.makeareadme.com)
- [Making READMEs readable](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md)
- [CITATION.cff documentation](https://citation-file-format.github.io)
- [GitHub documentation on CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
- [Generate CITATION.cff files](https://citation-file-format.github.io/cff-initializer-javascript/#/)
- [Citation File Format GitHub](https://github.com/citation-file-format/citation-file-format)
- [TU Delft Guidelines on Research Software: Licensing, Registration and Commercialisation](https://zenodo.org/records/4629635)
- [TU Delft Research Software Policy](https://doi.org/10.5281/zenodo.4629662)
- [Choose a license](https://choosealicense.com)
- [tl;drLegal](https://www.tldrlegal.com)
- [The Turing Way - Licensing](https://the-turing-way.netlify.app/reproducible-research/licensing)
- [GitHub's guide to setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
- [GitHub's own CONTRIBUTING guide](https://github.com/github/docs/blob/8ef6dfa3a1400156aee603c7642485ebba2161b8/.github/CONTRIBUTING.md)
- [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)

:::