Data

Tools

Indexes

Applications

Experiments

Open Source Science

documentation

This is a course on software documentation for researchers developed by the Research Software Engineering team and IT Services at the University of Sheffield.

https://github.com/fair2-for-research-software/documentation

Science Score: 52.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ✓
    CITATION.cff file
    Found CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Academic email domains
  • ✓
    Institutional organization owner
    Organization fair2-for-research-software has institutional domain (rse.shef.ac.uk)
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (10.8%) to scientific vocabulary

Keywords

documentation fair4rs reproducible-research research-software-engineering rse software-engineering
Last synced: 6 months ago · JSON representation ·

Repository

This is a course on software documentation for researchers developed by the Research Software Engineering team and IT Services at the University of Sheffield.

Basic Info
Statistics
  • Stars: 1
  • Watchers: 1
  • Forks: 1
  • Open Issues: 4
  • Releases: 0
Topics
documentation fair4rs reproducible-research research-software-engineering rse software-engineering
Created almost 2 years ago · Last pushed 6 months ago
Metadata Files
Readme Contributing License Code of conduct Citation Security

README.md

01 Build and Deploy Site

Research Software Documentation

This repository contains a training module on documenting research software that is part of the training provision for research computing at the University of Sheffield and developed as part of the FAIR2 for research software course.

Course description

This course will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience.

Course overview

This course introduces the different ways to provide other researchers with useful documentation for your software.

  • Writing informative README files
    • Writing installation instructions
    • Writing usage instructions
    • Writing contribution guidelines
  • Improving code readability
    • Doc-strings for functions
    • Usage examples for functions
    • Type hints
  • Publishing documentation websites
  • Command line interfaces with usage instructions

There is information about publishing a software package and providing metadata and citation details in Modules 6 and 7 of this course.

Contact us

Please contact Research & Innovation IT or Research Software Engineering at the University of Sheffield.

Owner

  • Name: UoS FAIR2 for research software
  • Login: FAIR2-for-research-software
  • Kind: organization
  • Email: rse@sheffield.ac.uk

Training in FAIR (Findable, Accessible, Interoperable, Reusable) and Reproducible research software skills at the University of Sheffield

Citation (CITATION.cff) 

# This template CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to replace its contents
# with information about your lesson.
# Remember to update this file periodically, 
# ensuring that the author list and other fields remain accurate.

cff-version: 1.2.0
title: FAIR4RS Documentation course
message: >-
  Please cite this lesson using the information in this file
  when you refer to it in publications, and/or if you
  re-use, adapt, or expand on the content in your own
  training material.
type: dataset
authors:
  - given-names: Joe Salvador Thornhill
    family-names: Heffer
    email: j.heffer@sheffield.ac.uk
    affiliation: The University of Sheffield
    orcid: 'https://orcid.org/0000-0001-8733-1117'
abstract: >-
  Software documentation helps you and others to use your software
  successfully in the future and to read your code ensuring that its
  value is sustained. This course introduces the different ways to
  provide other researchers with useful documentation for your software.
license: CC-BY-4.0

GitHub Events

Total
  • Issues event: 5
  • Delete event: 10
  • Issue comment event: 9
  • Push event: 77
  • Pull request event: 19
  • Fork event: 1
  • Create event: 12
Last Year
  • Issues event: 5
  • Delete event: 10
  • Issue comment event: 9
  • Push event: 77
  • Pull request event: 19
  • Fork event: 1
  • Create event: 12

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 26
  • Total pull requests: 45
  • Average time to close issues: 21 days
  • Average time to close pull requests: 1 day
  • Total issue authors: 2
  • Total pull request authors: 2
  • Average comments per issue: 0.42
  • Average comments per pull request: 0.96
  • Merged pull requests: 41
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 8
  • Pull requests: 27
  • Average time to close issues: 12 days
  • Average time to close pull requests: about 12 hours
  • Issue authors: 2
  • Pull request authors: 2
  • Average comments per issue: 0.0
  • Average comments per pull request: 0.89
  • Merged pull requests: 23
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • Joe-Heffer-Shef (6)
  • ns-rse (1)
Pull Request Authors
  • Joe-Heffer-Shef (42)
  • ns-rse (6)
Top Labels
Issue Labels
Pull Request Labels
type: template and tools (4) CI (2) episodes (1)

Dependencies

.github/workflows/pr-close-signal.yaml actions
  • actions/upload-artifact v3 composite
.github/workflows/pr-comment.yaml actions
  • actions/checkout v3 composite
  • carpentries/actions/check-valid-pr main composite
  • carpentries/actions/comment-diff main composite
  • carpentries/actions/download-workflow-artifact main composite
.github/workflows/pr-post-remove-branch.yaml actions
  • carpentries/actions/download-workflow-artifact main composite
  • carpentries/actions/remove-branch main composite
.github/workflows/pr-preflight.yaml actions
  • carpentries/actions/check-valid-pr main composite
  • carpentries/actions/comment-diff main composite
.github/workflows/pr-receive.yaml actions
  • actions/checkout v3 composite
  • actions/upload-artifact v3 composite
  • carpentries/actions/check-valid-pr main composite
  • carpentries/actions/setup-lesson-deps main composite
  • carpentries/actions/setup-sandpaper main composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
.github/workflows/sandpaper-main.yaml actions
  • actions/checkout v3 composite
  • carpentries/actions/setup-lesson-deps main composite
  • carpentries/actions/setup-sandpaper main composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
.github/workflows/update-cache.yaml actions
  • actions/checkout v3 composite
  • carpentries/actions/check-valid-credentials main composite
  • carpentries/actions/update-lockfile main composite
  • carpentries/create-pull-request main composite
  • r-lib/actions/setup-r v2 composite
.github/workflows/update-workflows.yaml actions
  • actions/checkout v3 composite
  • carpentries/actions/check-valid-credentials main composite
  • carpentries/actions/update-workflows main composite
  • carpentries/create-pull-request main composite