Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Before you Start

Before you author a cookbook take the following advice into consideration to get the most impactfull results.

Cookbook Considerations

When you start authoring a cookbook consider the following things:

  1. Self Containment

    A cookbook should be self contained. All notebooks that represent a cookbook should run from first to last cell. This should ideally apply to local execution as well as on TU Wien’s BinderHub.

  2. Open Science Principles

    Try to adhere to the best of you abilities to open science and free and open-source software practices (FOSS). This also includes licensing of your cookbook so that others can attribute your work when reusing it.

  3. Clear Prerequisites

    Be explicit about the domain knowledge and programming skills required for the user to learn from the cookbook.

Notebook Considerations

A notebook is the smallest unit in a cookbook. It can be viewed similarly as a chapter of a book.

When writing a notebook keep the following things in mind:

  1. Runtime Optimization

    Evaluate runtime of the cells and the notebook as a whole; the faster is generally the better. Identify opportunities to reduce long-running operations by creating smaller sample datasets and using parallel processing techniques. Possibly you are using for-loops in Python where one can exploit numpy for matrix operations. As run time is a factor of infrastructure, try to test your notebook on the TU Binderhub for a good reference point.

  2. Content Organization

    Consider the cell count of your notebooks. Should very long notebooks be split into multiple focussed notebooks? Reversely, your notebooks can also be to fragmented and merging similar content notebooks to one can help readability.

  3. Text to Code Balance

    Taking note of Knuth’s literate programming paradigm we should strive to use Markdown cells whenever we introduce a new code cell to explain its existence and functioning. The user should never be left wondering why does this line of code exists?!

  4. Code Abstraction Strategies

    Writing code leaves us with the choice of exposing features or hide them away. Abstraction is at the heart of programming; it is impossible to learn all aspect of a program, so to make life easier for the user, we hide away logic that is irrelevant for the program to be used. Besides, it is easier to argue with abstracted code and helps maintain big code projects. We essentially have to ask two questions when authoring a cookbook;

    • Is a code snippet easential to a deeper understanding of the topic?

    • Or, does it serve only a technical purpose rather than an educational one?

    If your answer lean towards an affirmative for question two, then try to abstract the code by creating functions or user-defined classes.

  5. Data Context

    Some notebooks will need access to external datasets. Have a look at the dedicated data chapter to explore possibilities to add external data to notebooks during runtime. When using external data make sure to provide an introductory explanation of your dataset.

Cookbook Prerequisites

Authoring Cookbooks requires a basic understanding of the programming language of your choice which includes project and dependency management. In addition, one needs to have an understanding of a suite of tools that enable the development workflow of TU Cookbooks.

  1. Jupyter and/or Markdown

    Authoring TU Cookbooks requires either knowledge of Jupyter and/or Markdown. It is possible to use exclusively markdown text files by adding code cells to markdown files, like so:

    ```{code-cell} python
hello = "hello"
there = "there"
phrase = f"{hello}, {there}!"
print(phrase)
```

    This means that one should familiarise with markdown syntax. Myst is the book building framework which adds further extensions to markdown for scientific reporting, such as, citing academic work, e.g., [](doi:10.5281/zenodo.6476040). Have a look at the extensive mystmd guide for more inspiration.

  2. Git

    The basic workflow from local development to deployment of the static pages and BinderHub environment requires knowledge of Git. Besides a great tool for version controlling of software, tracking development, and collaborative work, it takes care of automation in the TU Cookbooks project (learn more about this in CI/CD automation). Management of this project is in large taking place in our TU Wien GitLab “TU Cookbooks” group. Here, one can find cookbook templates, such as the TU Cookbook Python Template, and documentation, such as this cookbook authoring guide.

    Check out this TU Wien Git Workshop organised by the Research Data Group to get started with Git.

Besides Git, Jupyter, and Markdown, other desirable skills are:

TU Cookbook Author Guide
TU Cookbook Author Guide
TU Cookbook Author Guide
Getting Started