Open Documentation Hour, 19th July 2024
In this recording, we attempt to answer one of the most commonly asked questions about the Diátaxis documentation framework - what is the difference between a how-to and a tutorial?
Big thank you to @keirthana for running this session!
00:00 Intro
00:05 Updates
02:05 Presentation starts
02:45 How-to vs. a tutorial
03:45 Cooking example
05:30 Similarities between the two
06:10 Differences between working and learning
11:40 More confusion
14:20 Further reading
15:20 Diátaxis definitions
17:30 Questions
17:40 When do you need a tutorial?
22:00 How do you decide if you need one or the other?
23:00 How simple should a How-to be
25:00 Other options on how the two differ
28:00 Tutorials that glue the product together
32:00 Tutorials for teaching, How-tos for general use
35:00 How do you know if your tutorial is effective?
37:00 What’a a good advanced-level tutorial?
46:00 Should you use screenshots?
47:00 Where is the single source of truth?