documentation.qmd

# Documentation {#sec-documentation}

It takes time, but extensively covering your project with clear documentation is the best (and IMHO, the only) way to ensure your code will be understood, therefore reproduced and trusted. The reader should be able to obtain the same outputs as you by only following your instructions. Assume that the reader might be less familiar with you with the tools you used. Your documentation should cover:

- What the study is about.
- How the project is organised (e.g., explain what each folder includes, and what file names mean).
- Reproducibility instructions:
    + How to download necessary files to run the code (e.g., raw data, WAV files).
    + Which external packages your code depends on (e.g., `dplyr`, `numpy`).
    + How to run the code (in which order to run the scripts).

How to properly document a project is a research topic on its on. Some tools have been developed to make documentation easier, and more automatized. For instance, most languages provide some form of programmatic way to register, update, and share which packages should be installed in order to run your code successfully, and which versions of them. We'll cover this later on.