Skip to content

Create template documents for GitHub Repositories §

Pattern Summary §

Create template documents for project repositories as a first step to attracting contributions.

Problem / Challenge §

Students and researchers are not attracting the contributors and maintainers needed to sustain their OSS projects. Consequently, research software is open in name only and risks being abandoned after initial release.

Pattern Category §

  • Building Community
  • Promoting Best Practices

Context §

A university with a large and diverse research cohort that is creating volumes of research outputs across all disciplines.

There is inconsistent awareness about the role of OSS standards in improving scientific quality and generating results that are reproducible and trustworthy.

Student and research repositories are missing the crucial documentation required to allow new team members to quickly understand, contribute and maintain the codebase.

Forces §

Labs and projects have expertise in computer science and coding. However, practitioners lack the knowledge and/or confidence to build the OSS communities needed to sustain their projects.

Researchers and development teams on open science/open source projects are already overburdened.

Solution §

Needs Analysis §

Review what documentation is (or isn't) in place on a sample of repositories.

Talk to a sample of students/researchers who are not using documentation to find out more. Important questions to ask relate to perceived challenges of writing documentation and their satisfaction levels with contributions to date.

Create resources §

Conduct a review of existing standard documentation templates.

Use these as a basis for standard templates that can be adapted for open source / open science project repositories:

Standard documentation templates usually include:

  • README.md: The main documentation file providing a comprehensive overview of the project, installation or deployment instructions, usage examples, and links to further documentation.
  • CONTRIBUTING.md: Guidelines for how contributors can help with the project and instructions about how to submit pull requests, report bugs or request new features.
  • CODE_OF_CONDUCT.md: Document outlining the behavior expected from contributors to foster a welcoming and respectful community.
  • Guides: Some repositories may require step-by-step guides, for example, a getting-started.md (for beginners) or an advanced-usage.md for more complex usage scenarios.

Promoting the templates §

Template documentation can be promoted to the OSS community in a number of ways including:

  • Showcasing documentation templates on the OSPO website.
  • An announcement on other OSPO channels e.g. mailing list, slack channels.
  • Linking in with relevant student organizations to share information.

Resulting Context §

Researchers and projects have access to templates that will enable them to promote their projects and enable potential contributors to get involved.

Additional learning from the University of California OSPO Network §

We identified this gap in documentation following a scraping exercise of university repositories on GitHub. During outreach to maintainers, we noticed that many didn’t have CONTRIBUTING.MD or CODE_OF_CONDUCT.MD files on their repos.

We started with a TL:DR about preparing for contributions but this was expanded into templates when we discovered that many projects didn’t know how to create their own documents; lacked the confidence about getting started; or were too busy to work on the documentation themselves.

Known Instances §

References §

README resources §

Contributors & Acknowledgement §

(in alphabetical order) * Ciara Flanagan, https://orcid.org/0009-0005-3153-7673 * Laura Langdon (University of California Davis)