Rework pills to be more suitable for both professional and student audiences

[peter-mlabs]

Subtasks:

• Provide pill-by-pill, runnable code snippets
• Provide more structured, open-ended exercises
• Ensure that the main text is entirely self-contained and that the exercises are optional
• Explain the purpose of the pills in the introduction

Overview

This task seeks to revise the pills to be either (or both) of:

• A learn-by-example introductory text which leaves little ambiguity and illustrates best-practices with Nix and it's design patterns.
• A learn-by-exercise text which illustrates the main concepts, and then provides thoughtful, structured exercises in which the reader is required to experiment.

The former is more suited for a "professional" audience who is learning Nix on-the-job with a specific use in mind (either a greenfield project for which they want to use Nix, or an existing Nix code base that they want to understand or modify.) This audience benefits from being able to rapidly read through the pills, follow along with the examples, and ensure that they can jump around while still having complete, working code available for reference and comprehension self-checks. Leaving some critical parts as "exercises for the reader" slows this down. It also decreases the confidence that the pills are targeted at a person in this audience; it is easy for this type of reader to say "Well, I don't have time to do this exercise, and I don't know that future pills won't require this of me, so I guess this isn't for me."

The latter approach is better suited for a "student" audience, such as actual students, hobbyists, or professionals without an immediate need to apply the material. Exercises -- especially well-structured, somewhat open-ended exercises that build upon each other -- are critical to encouraging readers to experiment and develop a deeper intuition for the language. These exercises should typically be designed to allow readers to self-validate their understanding, but should not be a barrier to struggling readers who should press on and revisit the exercise when they understand more. Whether or not example solutions are provided is a matter of preference, but my personal opinion is that this can be helpful to curious newcomers who may lack confidence.

Current deficiencies and strategy to improve

The pills, as they stand, do not seem to commit to either approach.

In the "professional" audience

For the "professional" audience, there are long-running examples in the text, but pill-by-pill code examples are not provided anywhere (as far as I can tell). This means that the nix pills will be unusable as a "refresher" on a given topic; its not possible to jump in, cd into a directory, and have all of the files available as they have been built up to that point in the text. In order to do this, a reader currently must start from the beginning and build these examples over time.

This is straightforward to rectify: we simply just include the code example.

Likewise, there are a minority of pills that leave critical parts as exercises, such as pill 14 which states:

Now it would be nice if callPackage made our derivations overridable. That was the goal of this pill after all. This is an exercise for the reader.

This is unhelpful for two reasons:

• Many of the previous pills didn't include any exercises, so the expectation that a reader will have to spend more time on pill 14 than they did on earlier pills in order to progress may come as a surprise
• The primary goal of the pill should not, IMO, be an exercise. If a reader was already struggling with this section, then this exercise will block them from further progress. If they weren't, then this exercise will likely not teach them anything.

To rectify this, we should convert existing exercises to examples.

In the "student" audience

Conversely, there are not enough exercises to make the pills engaging for a student audience, nor are the existing exercises sufficient for gaining a deep understanding of their respective topics.

This could be fixed as follows:

• Design intra-pill exercises for every pill. These exercises should be self-contained: all information needed to complete them should be contained within the pill itself. Provide solutions to these exercises, as they are more for comprehension-checking than for intuition-building.
• Design longer-running inter-pill exercises. These exercises should be relatively open-ended, thread through the entire series, and require some additional work, research, or experimentation to come to a satisfactory solution. One option may be to have readers construct derivations for their own code, or provide some other non-autotools projects to work with; the exercises could take the form of asking readers to write builders and derivations, and add the same or similar features to their own code alongside the examples in the text. Such an exercise would not need solutions, as the pills themselves and community repositories should illustrate the main concepts.
• Provide some "research" tasks: ask readers to look at some example code (perhaps from nixpkgs itself), and describe what they think the code does. Comparing our example implementations of callPackage with the "real" implementation (if such a thing exists) could be instructive as well.

[jonringer]

I think one issue is that there's not one problem that nix + nixos is trying to solve. nix-pills is more oriented around understanding so that you can apply it to the problems as they arise.

The nix-by-example seems to be more simliar to nix-tutorials and the rendered notebooks

I'm not saying that there shouldn't eventually be something like what you're asking, but I would see it in addition to the current nix pills.

[peter-mlabs]

I'll check these out as well! Perhaps separating my efforts across the two projects would be better