Skip to content

create-template-documents-for-github-repositories.md

Latest commit

 

History

History
99 lines (62 loc) · 5.67 KB

create-template-documents-for-github-repositories.md

File metadata and controls

99 lines (62 loc) · 5.67 KB
Raw
tags
Community Building
Promoting Best Practices

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.

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)