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.
@itamarst @abathur I'm familiar with the Diataxis framework, and we're actually trying to work within it. That handbook sounds useful, I'll have to study that.
My goal is to make sure that new Nix users get a realistic picture of what it's like working with Nix, which sometimes means knowing the idiosyncrasies and rough edges. For instance, there can be weird things with PYTHON_PATH, you may need to package something yourself, etc.
@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.
@itamarst @abathur I like the idea of "backwards design", so now I'm left wondering what is a useful end goal to have new users work towards that will put them into contact with the kinds of problems that exist in Nix today. Part of me still wonders whether that's the correct goal i.e. do you want to put users in contact with the rough edges (that's what the poll was originally about), or do you only want to show the happy path.
@zmitchell @abathur Goals change over time.
User doing the first tutorial in the series has different goal than user doing the fifth tutorial in the series.
If dealing with rough edge is something users will have to do, you need to teach it. But that doesn't mean it has to be the first thing you teach.
@zmitchell @abathur To give a concrete example: I have a book teaching basics of Docker, based on training material created with Carpentries method.
Chapter 1 covers one rough edge (need sudo on Linux, often) because large number of people will hit in in first 30 seconds. But otherwise is mostly golden path of CLI tool.
Chapter 2 is golden path end-to-end packaging of tiny Python program.
Chapter 3 then covers common networking problems users are very likely to encounter.
@zmitchell May help to have an example or two of what counts as hard/weird/rough here?
Is this, say, how to package something straightforward like a script that will `curl | jq` vs something thorny like how to package a project that expects to get dependencies from a language-ecosystem package manager?
Or more like how to package something that already squares with the stdenv's configure/make expectations vs one where you'll have to patch the makefile?
@zmitchell might be worth to have both styles even, this might be useful, unless you've seen it already - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ :)
@zmitchell I like using collapsible sections (collapsed by default) for edge cases. Sort of an opt-in kind of thing.
@meganesulli wrote a super helpful article that discusses this! https://meganesulli.com/blog/docs-for-everyone/
@LauraLangdon @zmitchell @meganesulli I really like collapsible sections for extensions or asides. Also, cross references between tutorials and the explanation/reference sections of the docs.
@zmitchell Show it and mark it as the hard stuff so one can skip it .