Week 6 - Documentation#

Today’s learning objectives

Topics for today:

  • Understand the different types of documentation relevant to software projects

  • Start using essential documentation best practices

  • Review the readability of your code

What to expect By the end of the seminar we would like you to have a documentation approach/system that fits your project requirements.

📆 Seminar schedule#

  • Welcome!

  • Reminder of the Code of Conduct

  • Discuss previous assignments [20 min]

  • Introduce assignments [15 min]

  • Work on assignments [50 min]

🙋 Discussion and questions#

  • Reflect on the fact that preparing a repo to become reproducible is already a documentation exercise.

    • You have already started working on dependency documentation and installation instructions.

    • Some have tests and notebook examples.

    • Readable code is documentation.

Warning

Some statements to provoke discussion:

  • Documentation is everything

    • What do you think is the main documentation source in a codebase?

  • Code is for computer, comments are for humans.

    • What is the role of comments in your code?

  • Readable code is sufficient for good code documentation.

    • Who should be reading your code?

  • Different users approach your code differently.

    • Can you think of different users and usecases?

    • Which documentation tools would you use?

👉 Go to collaborative document.

Assignments for Wednesday 26th of April#

The goal of the this week’s challenges and assignments is to find a documentation system/approach that works for your project specific needs.

Tip

💡 Tip: Add the FAIR cards to your github board to as a reference for FAIR documentation.

FAIR card - Project documentation#

_Essential_  
- [ ] [README](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md)
- [ ] [LICENSE](https://doi.org/10.5281/zenodo.4629662)
- [ ] [CITATION](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)

_Recommended_  
- [ ] Make use of [Github issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)
- [ ] [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)

FAIR card - Software documentation#

_Essential_  
- [ ] Installation instructions
- [ ] User documentation
- [ ] Developer documentation
- [ ] Source code documentation ([docstrings](https://numpydoc.readthedocs.io/en/latest/format.html))

_Recommended_  
- [ ] Examples and tutorials (Jupyter notebooks, videos, screencasts)
- [ ] Automate documentation building with [sphinx](https://coderefinery.github.io/sphinx-lesson/)
- [ ] Website ([github.io pages](https://pages.github.com/), [Readthedocs](https://readthedocs.org/), [JupyterBook](https://jupyterbook.org/intro.html)

_Optional_  
- [ ] Build [API reference](https://developer.lsst.io/python/numpydoc.html) from docstrings

Assignment 1#

Add essential files that make your software project instantly more Accessible and Reusable:

  1. LICENSE file

    The TU Delft released a high-level Software Policy that lists pre-approved open-source licenses.

    Note

    For more information, detailed TU Delft Research Software Guidelines about licensing, registration, and commercialization are available. This document also details the required steps to reclaim the copyright to your software (page 27) as TU Delft by default holds the rights to the software created by its employees.

Tip

💡 Tip: Licenses simplified by Choose a license and Software licenses in plain English

  1. CITATION.cff file

    You can add a CITATION.cff file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information. More information and compatible tools can be found in this repository.

Assignment 2#

Now that we have the minimum required for FAIR documentation for research software, let’s define a broader approach towards your project documentation.

Note

What do we mean by documentation system?

What no body tells you about documentation is that is not just one thing, but several. How-to-guides, tutorials, in-code documentation, knowledge-base and explanation of concepts can all be part of documentation. In the case of research software, Jupyter notebooks often are an essential documentation tool. Divio offers a great overview of the types of documentation.

  1. Define the documentation that you, your users, and your collaborators would need to understand and use your software.

  2. Make a todo list (GitHub issues) based on these considerations.

Tip

💡 Tip: Think about a minimum approach that improves your current situation, and a more ambitious approach.

Assignment 3#

Readable code and in-code documentation are important parts in making your code easy to understand To improve the readability of your code, you should consider:

  • Writing code comments that explain the why of the code and not the what.

  • Adding docstrings to (public) functions.

  • Using common naming conventions (check a style guide).

  • Adding whitelines and avoid compound statements.

Note

Every major open-source project (e.g. Numpy) has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It is much easier to understand a large codebase when all the code in it is in a consistent style.

  1. Checkout a style guide for your Programming language and review your code for the readability considerations listed above.

    • Would it make sense to adopt a style guide for your project?

    • What conventions do you find useful?

  2. Following style guides can be made easy with a linter. Review your code by running a linter (e.g. flake8 for Python, checkcode for MATLAB, IntelliSensefor C++, or lintr for R) to identify conflicts with the style guide.

  3. Make a todo list (GitHub issues) to improve the readability of your code.

Tip

💡 Tip: For Python, the recommended docstring styles are the Numpy and Google styles. Both can be interpreted by sphinx.

💪 Extra (optional) Assignments#

Materials#

Sphinx