> For the complete documentation index, see [llms.txt](https://christina-maimone.gitbook.io/teaching/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://christina-maimone.gitbook.io/teaching/tutorial-format.md).

# Tutorial Format

Your tutorial will consist of 3-6 sections, along with some *brief* introductory and concluding materials.  Each section consists of an **exercise**, preceded by the materials you need to teach learners how to do the exercise.

Where possible, you want to create a **single file** that contains all of your tutorial materials: background, explanations, graphics, examples, and exercises.  If you need to use multiple files, there should be one main file that contains links to other files; return to the main file regularly to reorient participants.  

![](/files/-MbIsFnojlB8O7dsbWFo)

### **File Format**

**Notebooks when you can**: For languages with a well-developed notebook technology (R, Python, Julia, Mathematica, MATLAB), we recommend you use a notebook.  Notebooks allow you to include multiple types of information, learners can write and execute code in the file, and they can take notes in the same file they're learning from.

* Jupyter notebook for Python and Julia
* R Notebook or R Markdown file for R
* MATLAB Live Editor

**HTML files**: For tutorials that include code but are for a language without a well-developed notebook technology, a static html file can be a good option. If there's a fiddle or online tool available to use for exercises, you can link to those exercises in your file.  HTML files also support code formatting and make it easy for participants to copy code from to paste into their own programs.  Example: [Regular Expressions Tutorial](https://github.com/nuitrcs/regex_workshop/)

**Well-commented scripts**: For programs where you and your learners will need a script file, create one with extensive comments.  This may work well for programs like Stata or Bash.

**Slides**: Slides can be useful when teaching how to use a tool with an interface; for other types of tutorials, use one of the other formats above instead.  Do not use slides for a typical presentation full of bulleted lists.  Slides should have code, output from running code, screen shots, images of the tool, etc.  You are not giving a lecture.  

*Note: we've found that code-heavy slides can be effective for teaching coding during in-person workshops where slides are displayed on a screen and learners still have their own computers to take notes and do the exercises.  For virtual workshops, slides are more difficult because many learners do not have two screens or large screens, switching between programs can be hard, and it can be difficult to watch what's happening on Zoom and look at a code file at the same time.*

**Tip:** Looking for a way to automatically create a html file with code and executed code output?  R Markdown will process code chunks for bash, sql, octave, [stata](https://www.ssc.wisc.edu/~hemken/Stataworkshops/Stata%20and%20R%20Markdown/StataMarkdown.html), [sas](https://www.ssc.wisc.edu/~hemken/SASworkshops/Markdown/SASmarkdown.html), and [many other languages](https://bookdown.org/yihui/rmarkdown/language-engines.html). You don't need to know (hardly) any R to use R Markdown to create files for other languages.  While this is a useful way to create an html file for learners to use, we don't recommend having participants use RStudio themselves during a workshop to execute code *unless the workshop is about R*, as having participants in a non-R workshop set up and run R/RStudio will be confusing.

###

###


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://christina-maimone.gitbook.io/teaching/tutorial-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.