Write a Tutorial
Tutorials are learning experiences to give our users confidence and experience in using Sienna.
Prepare
- If you have not read Diataxis, first read it in its entirety.
- If you have read it, skim the pages on Tutorials and the difference between a tutorial and how-to guide to refresh your memory and refer back throughout the process.
- Look at an example:
PowerSystems.jl's Working with Time Series
Historically, many of Sienna's "tutorials" have blended all 4 types of documentation in the Diataxis framework. If you are editing, be prepared to move material to related Explanation and How-to pages and into function docstrings in the APIs as you work.
If you starting a new tutorial, ask yourself if a tutorial is appropriate for what you're trying to show, or if you should be writing a how-to instead. See also how to Write a How-to Guide.
Follow the Do's and Don't's
The Diataxis Tutorials page should be your main reference as you write, but in addition, use these functional and aesthetic guidelines to ensure we follow Diataxis and avoid common pitfalls from previous versions of Sienna documentation:
- Give it a story
- Make it reproducible
- Make it effortless to read
- Make it realistic and relatable
- Only show relevant log and return statements
- Remove other types of documentation
- Follow the Guidelines on Cleaning Up General Formatting
- Look at the compiled .html!
Give it a story
The tutorial should have a logical flow, rather than be a series of disconnected code demonstrations.
Use a series of julia markdown blocks. These won't be compiled, failing the intention of a tutorial and introducing high likelihood of errors as syntax changes.
```julia
<Some code here>
```Make it reproducible
A user should be able to copy and paste every code block in the tutorial in order and get the exact results seen on the documentation page.
Display all code, starting from using SomeSiennaPackage. Example: See Working with Time Series.
Use #hide or @setup blocks.
Make it effortless to read
Split code examples into ideally 1 (to 3) lines ONLY, with a short preface to explain what each line is doing, even if it's obvious to you.
Use blocks of example code and/or return statements that go over 1 screen length in the compiled .html. They are very hard to follow and allow a user to tune out or give up.
Make it realistic and relatable
Take the time to define some realistic example data.
Use zero() or one() for all example data.
Only show relevant log and return statements
Configure the logger or load/build a System that returns very few log statements. Use semi-colons at line ends to hide return statements if need be.
Show extensive or confusing log or return statements that bog down a reader with information that isn't directly relevant to what you're trying to teach.
Remove other types of documentation
Particularly when editing existing material, watch out for material that should be moved elsewhere according to Diataxis principles:
Preface each call to a new function with a hyperlink to that function's docstring so the user can find more detail
Include definitions and details about different keyword arguments or versions of a function in the tutorial itself. Some basic information is OK, but details and examples live in the docstrings, and they especially shouldn't be included in the tutorial in lieu of being in the docstrings.
Follow the Guidelines on Cleaning Up General Formatting
Follow How-to Clean Up General Formatting.
Look at the compiled .html!
- Compile the tutorial regularly and look at it
- Check all code examples gave the expected results without erroring
- Check for length of the code examples and iteratively adjust to make it easy to read