Writing documentation

Writing good documentation is very important for new people to understand how to use things. Often, we do not have time to write good guides, because we are having deadlines or other things to do that are more interesting and less boring than writing down what we already seem to know so well.

This guide is a small guide on how to write a good guide. It does not aim to provide an explanation on how to write the perfect documentation, because these resources already exist on the internet. However, it should make at least curious on how to write documentation with some short general rules:

Think like the reader
Go step by step
Be precise
Follow standards
Discuss

In the second part of the tutorial, we will focus on how to write documentation especially for this project.

So, scroll down if you want to start reading there.

Example on writing documentation in general

When you explain how things work, it is often better to take it step by step. Also, do not hesitate to make small steps. Tiny ones.

Keep in mind to think like the reader:

What is the previous knowledge about a topic
- Most of the people reading our docs are probably students, so maybe they are not familiar with all git commands and Linux tricks.
Provide a structure/agenda for your guide

Let us say you want to write a guide about the installation of Miniconda, which contains a lot of steps and the installation process looks like this example.

Example 1: Not so good

cd ~
mkdir tmp
cd tmp
wget SomeInstallationFileForMiniconda

chmod u+x SomeInstallationFileForMiniconda
./SomeInstallationFileForMiniconda

conda init bash
export PATH=/home/<YOUR\_USERNAME>/miniconda3/bin:$PATH

conda create -n new-environment python=3.9
conda activate new-environment

cd ~
mkdir repos
cd repos
git clone git@my-repo-url
cd my-repo
pip install -e .

How can this guide for an installation look better? Well, while writing think of yourself explaining the same installation procedure to a colleague. You would probably tell some of the commands, but in between you would also briefly discuss what they are doing. Maybe you are experiencing an error at some point. Maybe you want to give some more background knowledge in case the reader does not have it. In the case of our team it very important to give these kind of hints, because we are working in an interdisciplinary environment and followed different educational paths.

Now, let’s see how the installation could look like. Let us assume we already wrote an introduction, the prerequisites are clear, and we are just explaining the installation itself.

Example 2: Better

Now this is the better version, because it breaks down the process into:

Downloading the installation file
Installing conda
Troubleshooting some common problems that can happen during the installation
Showing what would be the next step after the installation

cd ~
mkdir tmp
cd tmp
wget SomeInstallationFileForMiniconda

First, we are navigating to our home directory and create a temporary directory where we store the Miniconda installation file. With the wget command, we download the file. Note that there are different versions of the installer, depending on which operating system you use. A full list of installers can be found on the Miniconda webpage . The reason why we are using Miniconda and not Anaconda is because it takes less disk space. As soon as we have downloaded the installer file, we can continue with the installation.

chmod u+x SomeInstallationFileForMiniconda
./SomeInstallationFileForMiniconda

We have to make the installer executable and run it. During the installation process itself, just follow the standard recommendations and paths that the installer selects during the installation. After the installation it can be possible that you have to do some tiny adjustments. With

conda init bash

you can modify your shell to show the conda path. And with

export PATH=/home/<YOUR\_USERNAME>/miniconda3/bin:$PATH

you are adding conda to the PATH variable. That should be done automatically during the installation, but sometimes it does not work properly. You can verify the installation by typing:

conda --version

After the installation is complete, we can create our conda environment.

conda create -n new-environment python=3.9
conda activate new-environment

Note that we are using Python 3.9 in our environment. This is because we are having some dependencies with another library, which will be explained in more detail in the remarks section. If you are running the installation on macOS, please find additional resources in the respective guide how to use conda environments on macOS. We can now start to clone our repository and install the dependencies for the project.

cd ~
cd repos
git clone git@my-repo-url

If you have not done yet, you can create the repos directory using mkdir repos. Please read this other guide that explains how to use Git. After you cloned the repository, we can navigate in there and install our dependencies.

cd my-repo
pip install -e .

This can take up to three minutes. If you are running into any problems during the installation please contact one of the other team members and verify whether it works for them or try to find a fix if you know how to approach it. If you have fixed errors that happened during the installation, please put a note into this installation guide, so, other people with the same issue have an easier time to solve it.

What is now better in this second example are the explanations for every step. For your brain it is way easier to come back to one of these steps, and you learn way more about what you are doing when there are small explanations than when just copy and pasting console commands.

Try to group commands or tiny steps that belong together, otherwise it looks a bit scattered. But also do not have to many loose blocks flying around.
Do not write too much, but take some time to explain some of the backgrounds even if you think it is clear. If there is a lot of background, you can also link to some page in the internet which already has done the work and provides a tutorial. Finally, make sure that you are writing in a consistent style and provide enough examples.
Whenever your guide is finished, share it with others and discuss. It is probably not perfect (yet) and other people might have valuable feedback from their own experiences with the problem you are describing.

Writing documentation for the automatic calibration

In this section, we will go through the specific processes that are important when writing documentation:

Installing quarto
Structure of the files
Adding a navigation entry
Advanced features of quarto

Installation of quarto

In the tergite-autocalibration repository we are using Quarto to render documentation. Quarto is very versatile and can - among other document types - render markdown and Jupyter notebooks. If you have been following the steps in the developer guide introduction, you should have quarto already installed. Otherwise, you can do it by running:

pip install quarto

To render a simple preview of your documentation, please open a terminal inside the documentation folder and run:

cd documentation
quarto preview

This will open a browser window with the rendered quarto documentation pages.

Structure of the documentation

Maybe you noticed that on the top-level of the repository there are two folders, one called docs and another one called documentation. This is because they have two different purposes:

documentation: Contains the markdown files and Jupyter notebooks to create the documentation from. These are the files that you edit.
docs: Is the output HTML after running quarto render, which is displayed on the website. You do not edit these files. They will always be generated from the files in the documentation folder.

Now, let us have a look at the documentation folder, because this is the one we are working with the most. It is structured:

.assets: There you put images and style/formatting material.
.quarto: Do not touch this folder and do not commit it to git, because it contains temporary files during the rendering process.
developer-guide, nodes and user-guide: Contains the respective content for the pages.
Then there are a couple of pages from the top-level of the documentation.
And a file called _quarto.yml. This file is important, because it defines how things are rendered.

Adding a navigation entry in the `_quarto.yml` file

In here, the most relevant to be touched during adding documentation is the sidebar section. Imagine you are adding a new page e.g. about a calibration node, and you want to add it to the navigation. Then, you would add an entry at the correct position in the _quarto.yml file for the sidebar.

  sidebar:
    style: "docked"
    search: true
    contents:
      - section: "Node Library"
        contents:
          - text: "Overview"
            href: available_nodes.qmd
          - text: "Resonator spectroscopy"
            href: nodes/resonator_spectroscopy_node.qmd
          - text: "My new node"
            href: nodes/my_new_node.qmd

It is pretty self-explaining where to put the node when you see the rendered version in your browser.

Useful features of quarto

As you noticed, quarto does not render from normal .md markdown files, but from .qmd quarto markdown files. These are extending the markdown functionality with some special features. Here, we will show them along with some normal useful feature from markdown.

Code highlighting

Imagine you want to have a block to show code. What you write inside your markdown file would be:

```python
variable = 123
print("Hello world")
```

And the output would look like:

variable = 123
print("Hello world")

Graphs

For the calibration nodes, we are using a graph to chain them. This graph is rendered with mermaid.

```{mermaid}
graph TD
    A[Resonator Spectroscopy] --> B(Qubit Spectroscopy)
    B --> C[Rabi Oscillations]
        
    click A href "nodes/resonator_spectroscopy_node.html"

    style A fill:#ffe6cc,stroke:#333,stroke-width:2px
    style B fill:#ffe6cc,stroke:#333,stroke-width:2px
    style C fill:#ffe6cc,stroke:#333,stroke-width:2px
```

With the style attribute, you can define the colour of the node. With the click attribute, add a link on a node inside the graph.

Next steps:

When you reached the point that you are already writing the perfect documentation, you are probably also done reading the documentation. So, no next steps to read up upon. You can now write even more documentation or just code and explore quantum physics :)