Recent searches
Search options
If you were going through a #tutorial series, would you rather it avoid all hard/weird cases and rough edges, or would you rather be shown the hard stuff incrementally so you know how to handle it?
The #nix #documentation team is spinning up a tutorial series and I’m trying to decide what the best path forward looks like. #docs
@zmitchell https://documentation.divio.com/ might be helpful—there's two different goals that might be conflated here, what that model calls "tutorials" vs "howtos".
@itamarst @zmitchell Zach is helping the documentation team apply diataxis/divio, so it might help to drill down if you have hard-won insight from applying it?
I may be projecting, but I read Zach as asking where to aim between golden-path tutorials that risk under-preparing people for fairly common challenges and tutorials that explore something thorny enough to hit these challenges at the risk of intimidating some readers by showing more warts and dragging in more concepts?
@abathur @zmitchell AIUI, the goal for the tutorial part of the four quadrants is to just get people doing something as minimal as possible, just so they have a success. Which suggests trying to minimize edge cases you expose _unnecessarily_. So if it's "10% of people will hit this during initial install", yeah cover that, but if it's "10% of _packages_ will hit this" or "this is Python-specific" or whatever, you don't cover that in a tutorial, you cover that in a howto.
Put another way—
@abathur @zmitchell —I would try to limit it to practical tasks everyone (or almost everyone) would do. And if there are a lot of those tasks that are fundamental, try to do them iteratively. I.e. you structure it so you can stop at any point, as opposed to having digressions mid-way.
This isn't great:
1. Let's to do task A.
2. But that involves some Details, so let's dive into that!
3. We need to do B in order to succeed with A, so let's dive into that.
4. Now that we're done with B, let's get back to A.
5. OK we're done with A.
This is better:
1. Let's do very simple task A.
2. Now that we've done task A, let's try a more complex task B that builds on what we've learned but adds a new concept.
3. Now we'll do C, that builds on A and B.
@abathur @zmitchell As a complete beginner I want to know why I should bother spending any time on this at all (is it useful? is it too difficult to learn? will it take me weeks to get any benefit?) and then I want to know enough to go play with it and be able to make sense of the rest of the docs.
So question is not "keep it simple" vs "show hard stuff", it's "is the hard thing relevant to user's current goal in their learning journey".
@abathur @zmitchell A helpful approach to avoid adding unnecessary content is backwards design (https://cdh.carpentries.org/guiding-principles.html#backward-design).
Start with the task you want to the user to achieve, work backwards to what they have to learn to achieve that task, and only cover that and no more (you can always link to extra resources elsewhere in docs).
@abathur @zmitchell The Carpentries Curriculum Development Handbook is in general quite useful: https://cdh.carpentries.org/
It's a step-by-step process that should work well for tutorials.
@zmitchell @itamarst @abathur It's because we don't properly explain capabilities and least-security principles to developers. The Nix store is somewhat capability-oriented and definitely contains a content-addressed substore.
I half-agree with you. Nix should always make sense; users should be able to conceptualize what the Nix daemon does to the store.