-
-
Notifications
You must be signed in to change notification settings - Fork 114
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rework pills to be more suitable for both professional and student audiences #196
Comments
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. |
I'll check these out as well! Perhaps separating my efforts across the two projects would be better |
Subtasks:
Overview
This task seeks to revise the pills to be either (or both) of:
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:
This is unhelpful for two reasons:
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:
callPackage
with the "real" implementation (if such a thing exists) could be instructive as well.The text was updated successfully, but these errors were encountered: