Skip to content

Ending documentation

Questions

  • How can the user understand how to run your program and what it does?
Learning outcomes of 'Documentation'

learners

  • know the most important sections for a full public README
  • can make a installation instruction
  • can make citation info
  • know how to find instruction of going to more sophisticated documentation
Content

  • content of README

    • installation
    • get started
    • test
    • citation

  • Revisit licence

  • View other possibilities

    • Wiki
    • GitHub pages/ReadTheDocs
    • MkDocs/sphinx

Revisiting documentation

Documentation comes in different forms

  • Tutorials: learning-oriented, allows the newcomer to get started
  • How-to guides: goal-oriented, shows how to solve a specific problem
  • Explanation: understanding-oriented, explains a concept
  • Reference: information-oriented, describes the machinery
  • In-code documentaion — docstrings

Not to forget

  • Project documentation:
    • requirements: what is the goal of the software, risks, platforms
    • the analysis: pseudocode and UML
    • risk analysis

There is no one size fits all: often for small projects a README.md can be enough (more about md format later).

Where are we?

DONE

  • ☑ In-code documentation
  • ☑ Project documentation:
    • requirements: what is the goal of the software, risks, platforms
    • the analysis: pseudocode and UML
    • risk analysis

Finalize today

  • ☐ README
    • ☐ Installation instruction
    • ☐ Tutorial: get started
    • ☐ Citation

Further documentation for future projects

  • ☐ License
  • ☐ Tutorials: learning-oriented, allows the newcomer to get started
  • ☐ How-to guides: goal-oriented, shows how to solve a specific problem
  • ☐ Explanation: understanding-oriented, explains a concept
  • ☐ Reference: information-oriented, describes the machinery

Markdown

  • One of the most popular lightweight markup languages.
  • File extension .md makes it render directly in GitHub!
How does it look like? 
# This is a section heading in Markdown   

## This is a subsection header

Nothing special needed for a normal paragraph.

    This is a code block


**Bold** and *emphasized*.

A list:

- this is an item
- another item

A numbered list:

1. this is an item
1. items are numbered automatically

There is more:
![images](link to file),
[links](URL),
tables...

Read more

reStructuredText and Markdown

The README

Example content

  • About
  • Installation (with dependencies and testing)
  • Get started
  • Use cases
  • Citation

About

  • About the software
  • What does it do?
  • One (Punch-)line describing what it does.
    • Also in GitHub in upper right corner!
  • More information below below the first description

Installation section

Let's take a look at different READMEs

  • Also interesting: Is there any test that makes sure it is correctly installed?

Example

Get started

Use cases

would it be needed for your project?

Contributions

Licensing

  • We use GPL-3 in the project

Strong copyleft share-alike (GPL, AGPL) Derivative work is free software and derivative work extends to the combined project If the licenses of components are strong copyleft, one must use the same license

  • We can click on the license and a image will also show up!

    How does that look like?

    license_project

See also

Extra material about licensing

Acknowledgements

References/Citation

  • Think the same as for a scientific paper
Practical recommendations
Recommended format for software citation
  • Creator
  • Title
  • Publication venue
  • Date
  • Identifier
  • Version
  • Type

Katz, Chue Hong, Clark, 2021:

This is an example of a simple CITATION.cff file 
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: Druskat
    given-names: Stephan
    orcid: https://orcid.org/0000-0003-4925-7248
title: "My Research Software"
version: 2.0.4
doi: 10.5281/zenodo.1234
date-released: 2021-08-11

DOI and Zenodo

  • Digital object identifiers (DOI) are the backbone of the academic reference and metrics system.
  • CodeRefinery has an exercise to see how to make a GitHub repository citable by archiving it on the Zenodo archiving service. If you are interested, have a look here

Full examples

Examples of README files

Exercises

Exercises 30-40 min

  • We already have a file called README.md in /learners folder, that is used for information for the course participants.
  • Let's work with a README file for potential users. We can call it README-EXT.md

Intro

  • (External) users should be able to install and use the the complete tool, including dependencies
  • Repo work
    • Work on GitHub!
    • When modifying repo, use a group specific branch
    • When done, merge
  • In the end we do code review together of the merging conflicts
Markdown Cheat-Sheet 
# This is a section heading in Markdown   

## This is a subsection header

Nothing special needed for a normal paragraph.

    This is a code block

**Bold** and *emphasized*.

A list:
- this is an item
- another item

There is more:
![images](link to file),
[links](URL),
tables...

Group 1: Make 'installation instruction' in groups

Hints FIX
Make 'installation instruction'
  • Work together in group
  • Do git push first from local command-line, everyone!
  • 1 person types directly in GitHub
  • Create branch installation

  • Open the file learners/README-EXT.md

  • Be inspired by the examples above

  • Include the sections "Dependencies" and "Installing"
  • When done, make pull request to main

Group 2 Formulate an 'About' section

Make 'About' and 'Getting started'
  • Work together in group
  • Do git push first from local command-line, everyone!
  • 1 person types directly in GitHub
  • Create branch about

  • Open the file learners/README-EXT.md

  • Be inspired by the examples above

  • Include the section "About" which should give some background of what the program does and how to run it.

  • Include the section 'Getting started'

  • When done, make pull request to main

Group 3: Formulate "Sharing sections"

Make sections about 'Getting started', 'Citation', 'License' and 'Authors'
  • Work together in group
  • Do git push first from local command-line, everyone!
  • 1 person types directly in GitHub
  • Create branch sharing
  • Work with a CITATION(.cff) file
How?

Easier

Create a learners/CITATION file (no file extension) with most of the following lines

  • Creator
  • Title
  • Publication venue
  • Date
  • Identifier
  • Version
  • Type

Harder

  • open the file learners/CITATION.cff file
  • Fill it in
How can it look like?

```yaml cff-version: 1.2.0 message: "If you use this software, please cite it as below." authors: - family-names: Druskat given-names: Stephan orcid: https://orcid.org/0000-0003-4925-7248 title: "My Research Software" version: 2.0.4 doi: 10.5281/zenodo.1234 date-released: 2021-08-11

  • Open the file learners/README-EXT.md
  • Be inspired by the examples above

  • Include the sections

    • 'Citation', link to the CITATION(.cff) file
    • 'License' link to the license
      • try relative or absolute path!
    • 'Authors', List of the involved learners
    • 'Acknowledgements'
      • Add references that inspired or added algorithms to your code
      • Example

  • When done, make pull request to main

Example solution from last course

programming_formalisms_project_autumn_2024

Discussion of the README file

Discussion: Describe what you've done and why?
  • We go through the README!
  • Teacher makes Code review if needed

Going further with documentation

Wikis

HTML static site generators

There are many tools that can turn RST or Markdown into beautiful HTML pages:

There are many more ...

Do you like one style more?

Deployment on servers

GitHub, GitLab, and Bitbucket make it possible to serve HTML pages:

  • GitHub Pages (GH-pages) ← this is what we and many others use for course and tutorial material
    • Easy to set up. Part of GitHub Actions and CI
  • Bitbucket Pages
  • GitLab Pages
  • Read the docs ← this is what NBIS uses for some course material
    • hosts public Sphinx documentation for free!
    • Somewhat more possibilities, like having several versions of documentation to switch between. Good for different version releases of a software
    • Example: NBIS Introduction to Git

What contributes to reusability?

  • What contributes to you being able to reuse stuff that others make,

  • and others (or you) being able to reuse your stuff?

  • When you find a repository with code you would like to reuse, you may look at the following things to determine its reusability:

Note

  • Date of last code change

    ... is the project abandoned?

  • Release history

    ... how about stability and backwards-compatibility?

  • Versioning

    ... will it be painful to upgrade?

  • Number of open pull requests and issues

    ... are they followed-up?

  • Installation instructions

    ... will it be difficult to get it running?

  • Example

    ... will it be difficult to get started?

  • License

    ... am I allowed to use it?

  • Contribution guide

    ... how to contribute and decision process?

  • Code of conduct

    ... how to make clear which behaviors are unacceptable and discouraged? How violations of Code of conduct will be handled?

  • Trust and community

    ... somebody you trust recommended it?

Summary

Key points

Make sure it works for others or yourself in the future!

We are done!

Parts to be covered!

  • ☑ Source/version control
    • Git
    • We have a starting point!
    • GitHub as remote backup
    • Branches
  • ☑ Planning
    • ☑ Analysis
    • ☑ Design
  • ☑ Testing
    • Different levels
  • ☑ Collaboration
    • GitHub
    • pull requests
  • ☑ Sharing
    • ☑ open science
    • ☑ citation
    • ☑ licensing
    • ☑ deploying
  • ☑ Documentation
    • ☑ in-code documentation
    • ☑ finish documentation

See also

Documentation by CodeRefinery