2023-03-30 - Learning Journey Working Group - Meeting Notes #2

Development Documentation
1

2023-03-28 Learning Journey Working Group - Meeting Notes #2

Notes

  • We’re talking about getting the docstructure right, or getting going straight with the content.

    • @zmitchell suggest making a basic division into documentation categories

  • Tutorial vs. how-to

    • What is the difference between a tutorial and a how to guide?
      • Imagine airline pilot in simulator - in the end, you need to land it.
      • Tutorial - there is an end goal, but the purpose is learning, landing the plane is incidental
      • How to guide on the other hand - the goal is to land the plane by following some steps
    • @erooke
      • Tutorials - standalone monolithic units
      • How to guides - smaller andmore to the point that you try to achieve
    • @zmitchell - diff between tutorial and how to guide - tutorial doesn’t make any assumptions on pre-knowledge - how to guide does. How to guide is sparser.
    • @brianmcgee harder to separate the two things - how to guide - all about getting it done - tutorial, why are you doing it, explaining the concepts, better statement of pre-requisites
    • @erooke - looking at diataxis - tutorial is not supposed to explain why you are doing things - but how to guides do explain - goes a little bit against what we initially thought.
    • @zmitchell - boundaries are fuzzy

  • @brianmcgee - suggestion - create diagram to classify the thing that you are creating/copying from a different source.

    • Can we make it easier, make it our own?
    • @zmitchell
      • Tutorial
      • Recipes
        • sequence of steps
      • Concepts
        • conceptual knowledge & theory
      • Reference material
        • Links, apis and so on
    • We agree to start with this classification above.

  • @zmitchell let’s look at nix.dev shell tutorial.

  • @brianmcgee - suggestion - reshape nix.dev to the structure we want it to be - and then start filling it with the content that we want to see added.

    • @khaled - this can also involve - and will involve new writing.
    • @brianmcgee start with looking what’s inside nix.dev - and then start adding things from the outside. - identify what is missing.
    • @zmitchell - first order - move the existing content into the structure
    • new work
      1. Things that we are planning
      2. Stuff that anyone ever plans to contribute
    • @zmitchell - we looked at a blog post - and found that it didn’t fit in the existing structure - and therefore it was parked.
    • @brianmcgee - will create an issue to move stuff around on the existing website.

  • @zmitchell - come back to the nix shell tutorial - which elements should exist in it?

    • @erooke - most tutorial found were general - sales pitches - look at what you can do with nix - with some exceptions.
    • @erooke looked at inria tutorials.
    • @erooke quite a lot of video content
    • @zmitchell we can go two ways
      • alternative 1. nix-shell can solve this potential problem
      • alternative 2. nix-shell -p can be the focus
    • @zmitchell ran one qemu emulator as example using nix-shell -p
    • @erooke tutorial should be meaningful and achievable. Is it meaningful enough if you “just” include ripgrep on your command line, or do we need more?

  • @zmitchell how to create an ephemeral shell environment.

    • @brianmcgee - that’s the tutorial!!
    • tasks to complete in this tutorial
    • Daniele from diataxis stated the idea of the tutorial - I built the tutorial example - and now I want to go and build my own.
    • in our case - the ephemeral shell environments are cool - now I will make my own.
    • @brianmcgee - I need to convert html to pdf - and I will use pandoc for it. It graduates to I can create entire development environments.

  • @erooke - how to create a development shell.

    • @erooke - dev shells is a big nix use case, deployment is another one,
    • @erooke we create an ephemeral shell as first step
    • @zmitchell and as next step - in our next tutorial - we create a development shell.
    • iteratively go through the steps that takes you to the dev-shell that you need.
    • @brianmcgee @erooke - we will do a smaller tutorial about the ephemeral shell before we move on to a second tutorial about the dev-shell.
    • @erooke - it allows us to include more context - we can show why it’s useful.
    • @brianmcgee - common usecase - get ephemeral firefox - and removed after use.

  • @brianmcgee - we can also touch on garbage collection - and a natural progression from the shell tutorials

    • nix-store and nix-env and profiles.
    • @zmitchell - keeping first tutorial small - just the ephermal shell part.
    • @brianmcgee - for the future - how can I understand where my packages are coming from - for future tutorials. This was not straightforward to understand.
    • @khaled - using nix-locate - to find the package if the binary is known.

  • @zmitchell let’s create an issue with the tutorial ideas.

    • @brianmcgee - will go through how learned nix, and see what the missing pieces were - that we should get created.
    • @zmitchell it’s a great opportunity for us to “show the magic” and save people time.
    • @khaled clarifying regarding the desired tutorials list
    • @brianmcgee - nix is tricky, because you can get overloaded - not to show too much as people may get lost.

Tutorials

  • Ephermal shell nix-shell -p - warrants its own tutorial
  • follow on tutorial - dev shell

Action Items

2 Likes