Skip to content

Documentation

Questions

  • How can the user understand how to install and 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
  • Repo structure

  • content of README

  • View other possibilities

    • Wiki
    • GitHub pages/ReadTheDocs
    • MkDocs/sphinx

Why documentation?

Why?
What different kinds?
  • 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).

In-code documentation?
  • Comments, function docstrings, ...
  • Answers "Why?" not "What?"
  • Advantages
    • Good for programmers
    • Version controlled alongside code
    • Can be used to auto-generate documentation for functions/classes
  • Disadvantage
    • Probably not enough for users
Directory structure

  • Different projects should have separate folders

  • README file

  • Data (version controlled)(.gitignore)
  • Processed data intermediate
  • (Manuscript)
  • Results data, tables, figures (version controlled, git tags for manuscript version)
  • Src version controlled code goes here
    • License (here or in the 1st level)
    • Requirements.txt
  • Doc
  • index
  • .gitignore file
Did we follow this?

Well, this is a course and we needed to do a bit differently

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
  • Other levels like Wiki
What about the other documentation forms?

Further documentation for future projects

You can dig into this at a later state!

  • ☐ 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),
A|B|C
-|-|-
1|x|y
2|m|n

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
  2. items are numbered automatically

There is more: images, links

A B C
1 x y
2 m n
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

Acknowledgements

References/Citation

  • Think the same as for a scientific paper
Example with NextFlow 
nextflow -version

  N E X T F L O W
  version 24.10.2 build 5932
  created 27-11-2024 21:23 UTC (22:23 CEST)
  cite doi:10.1038/nbt.3820
  http://nextflow.io
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 at this Coderefinery webpage

Full examples

Examples of README files

Licensing

We covered this in Social coding

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

    How does that look like?

    license_project

Wikis

Exercises

Exercises 30 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
  • External users should be able to install and use the the complete tool, including dependencies
  • Also explore Wiki pages

Intro

  • Repo work
    • Work on GitHub!
    • When modifying repo, use a group specific branch
    • When done, merge/pull request
  • 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](documentatation.md#first-steps-for-all),

A|B|C
-|-|-
1|x|y
2|m|n

First steps for ALL

  • Work together in group of 2-3
  • 1 person types directly in GitHub
  • Do git push first from local command-line, everyone!

Group 1: Make 'installation instruction' in groups

Hints FIX
Make 'installation instruction'
  • 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'
  • 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.

  • When done, make pull request to main

  • Also add a Description/Punchline in the upper right corner at Project repo first page in the About section (The "setting wheel")

Group 3: Formulate a "Getting started" section

Make 'Getting started'
  • Create branch getting_started

  • Open the file learners/README-EXT.md

  • Be inspired by the examples above

  • Include the section 'Getting started'

  • When done, make pull request to main

formalisms/programming_formalisms_project_summer_2026/tree/main) in the About section (The "setting wheel")

Group 4: Formulate "Sharing sections"

Make sections about 'Citation', 'License' and 'Authors' and 'Acknowledgements
  • Create branch sharing
  • Work with a CITATION(.cff) file as well
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

Group 5: Make the Wiki Home page

Make the Wiki `Home.md´ page

Group 6: Make a Wiki sub page

Make the Wiki `known_problems.md´ page
Example solution from earlier course

programming_formalisms_project_autumn_2024

Discussion of the exercises

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

Going further with documentation

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

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