Skip to content

Ending documentation

Questions

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

learners

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

Content

  • content of readme

    • installation
    • get started
    • test
    • citation

  • Revisit licence

  • Update a Doc Index

  • View other possibilities
    • Wiki
    • GitHub pages/ReadTheDocs
    • MkDocs/sphinx

Revisiting documentation

Documentation comes in different forms

  • What is documentation?
    • 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 or README.rst can be enough (more about these formats 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

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

Install

  • We covered this in last session

Get started

Use cases

would it be needed for your project?

Contributions

Acknowledgements

References/Citation

  • Think the same as for a scientific paper

Practical recommendations:

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

Recommended format for software citation is to ensure the following information is provided as part of the reference Katz, Chue Hong, Clark, 2021:

Example

See also

Exercise

Intro

  • Revisit README-ext.md and update it with info after all our commits
    • About
    • Citing
  • Lastly, you may, if time allows, update the doc/index.md file that should describe the content
  • Do a git pull to have the same version of your project repo locally!
Update your documentation in groups
  • You can now work in GitHub directly

  • Do git push first from local command-line!

  • We already have a file called README.md, that is used for information for the course participants.

  • Let's continue to work with the README-EXT.md we used in last session.
Group 1: Work together and formulate an 'About' section
Group 2: Work together and formulate 'Getting started' section
Group 3: Work together and formulate 'Citation' section

Discussion

Discussion: Describe what you've done and why?

Licensing

See also

Extra material about licensing

Going further with documentation

See also

Documentation by CodeRefinery

Wikis

HTML static site generators

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

There are many more ...

Deployment on servers

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

GitHub pages

  • Easiest. Everything is local to GitHub
  • This lesson material

Read the Docs

  • Somewhat more possibilities, like having several versions of documentation to switch between.

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?

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