Adding tutorial 'Moving a bash script into its own file'

[nrdsp]

No description provided.

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[nrdsp]

I have read the CLA Document and I hereby sign the CLA

[fricklerhandwerk]

@nrdsp Thank you very much for the writeup. I really like how you explore the problem space and go into details and rationale.

Before going into detailed review though, I would like to point out a fundamental problem that we have everywhere in Nix documentation and figure out together how to proceed.

The purpose most pieces of Nix documentation are supposed to serve is almost always unclear. This is also the case here. There a mental model called Diátaxis which I think is very effective at guiding what to include, and more importantly, what to exclude. I strongly recommend taking an hour to read through it completely.

From now on speaking in terms of Diátaxis: your article has aspects of each category, but mostly appears like a Guide - not a Tutorial. This is because it is primarily about solving a specific problem (presenting a recipe) and not about teaching a skill (if not: what is that skill?). In that case it could be a lot shorter.

My question is therefore:

Do you have the time to rework the text to be more focused? I would of course help with that and organize my review around that goal.

If so, you could provide an optional section (or multiple contextual sections under <details>) on rationale and explanations, because I think the material is very good and the subject should be covered somewhere. Or you could split that out into a self-contained Explanation piece on handling shell scripts. This of course requires more time than just throwing things out.

A few more options:

• Do partial work for each text type and leave clearly labeled/categorized notes for posterity e.g. in nixos.wiki. That would save time and preserve what you have distilled.

• Merge this with minor issues fixed and leave the work of sorting it out for someone else to pick up (e.g. leave a note to a GitHub issue or this comment). I'm not a fan of this strategy, because I think losing context is expensive and requires more total time. But merging something is often better than nothing if available time is limited.

What do you prefer?

[nrdsp]

your article has aspects of each category, but mostly appears like a Guide

This did come to mind when writing, if would more properly fit a Guide rather than a Tutorial.

Do you have the time to rework the text to be more focused? I would of course help with that and organize my review around that goal.

So, if I understand correctly, you suggest adapting the text to become a Tutorial, specifically by making it shorter and more focused. I could do that. I do have time to rewrite the text and I'm happy to do what you suggest, only if I can understand properly. Reading through the Diátaxis model, it seems to me that wrapping a script and make it executable is the skill that we are trying to cover here (with a possible optional section covering alternative functions). Maybe adapting the steps to cover a simple example that anyone can start and complete, an Hello World! script, for instance.

If so, you could provide an optional section (or multiple contextual sections under <details>) on rationale and explanations, because I think the material is very good and the subject should be covered somewhere. Or you could split that out into a self-contained Explanation piece on handling shell scripts. This of course requires more time than just throwing things out.

I suggest that, instead of an optional section or multiple contextual sections under <details>, the rational and explanations for the specific example given in the current text could move out of the Tutorial altogether, becoming a how-to guide or a development story, with the necessary adjustments, in a blog post for SoN. In other words, in addition to extracting a Tutorial out from the current text, adapting it to cover a simple example such as wrapping a Hello Workd! script and executing it (first within a nix developer shell and then through nix build), for instance, I could submit it to be published as a blog post. Does this make any sense?

[fricklerhandwerk]

you suggest adapting the text to become a Tutorial[?]

It's up to you to decide, as long as you decide on something and make it really focused.

I think it is already closest to a Guide in terms of contents, due to the options you present and since you don't motivate the task (skilled readers know why or when to do these steps). It's fairly close to a Tutorial in terms of style, because you carefully lead through all the steps, and motivate them individually. It also has components of an Explanation because you lead the reader to the option which you favor.

If you make it

• a Tutorial: remove all options and add motivation in the beginning
• a Guide: remove all motivation and explanations, do not introduce things, just link to references, only show the necessary steps, keep options for reference
• an Explanation: rework the writing style, do not pretend to teach something but be explicit that this is an experience report that comes to certain conclusions

I consider a Guide to have the best value proposition: it will turn out the shortest text (efficient for author, reviewer, and reader), and help people get things done immediately. I will help with reviews in any case, though.

wrapping a script and make it executable is the skill that we are trying to cover here

In the mid term that would indeed be more valuable. This appears to be a much more common use case: have a bash script and make it work in Nix. Your text right covers the inverse, working with pre-existing Nix derivations. That is also valuable, this is why I prompted you to collect the insights in the first place. Eventually we should have Guides for both, but for the sake of getting things done we should merge whatever we have here first.

Side note:

I realized that by now we have this entire genre of what we call "development stories", and the Nix Pills fall into that category as well as some recent Summer of Nix posts, and to a large extent also this draft. It's a very detailed, technical way of telling "Why it's done that way and not another" or "How we got to where we are", helping people to understand deeply – that is an Explanation in Diátaxis terms. Which is also fine and useful, but targets a different audience and use case than we are focused on with nix.dev: software developers who want to get things done.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-35/21701/1

[fricklerhandwerk]

@nrdsp here is a nice in-depth pills-style development story for reference.

@sangster maybe you would like to take a look at nix.dev and see if you can contribute some of your findings or parts of your blog posts? We definitely need more material in that direction.

[nrdsp]

@fricklerhandwerk could you check the last updates?

Removed explanations, most if not all options too. The bash script example is more trivial as well.

[fricklerhandwerk]

It seems you still kept the detour to the final solution and wrapped it in tutorial-style instructions. This is fine if the contents of the detour are the learning objective. What is the learning objective you intend? Please state it first if you write a tutorial - see CONTRIBUTING.md for details.

Do you even want to write a tutorial in the first place, or is it supposed to be a development story? Because the contents, which haven't changed in structure, look more like a dev story, as said last time. You still appear not to have answered that question clearly before making more changes.

[nrdsp]

The detour is there to provide the learner with an insight into the exact steps that go into making a bash script executable (countdown.sh), including any dependency (pks.hello), then executing it. It does it without much explanations, if at all, but rather through the necessary practical steps: 1) read script, remove shebangs; 2) wrap it; 3) add any necessary dependencies; 4) execute it. If I were to give only the "simplified" version, then there wouldn't much to "learn how" through a step-by-step, hands-on approach, and I would instead have to explain it. The only thing I can see that might improve it is removing the explanation at the end, or rearticulate the "simplified" solution to have less talking.

[fricklerhandwerk]

That's exactly what I tried to make clear last time: the solution is so simple, it could (should) be a brief Guide. There is no obvious skill to learn here, so there is little point to make a Tutorial. There's some insight to be gained how it works under the hood, but that's an Explanation (in the style of Nix Pills) and contentwise the text is closest to that. We don't have a concept for expanding the Pills yet, but I think it would be worthwhile one way or another.

[nrdsp]

I think I'm now starting to get a better understanding of your comment above. Where would a guide live, in nix.dev or anywhere else? Are there any specific changes you would suggest if we were to make this a Guide?

[fricklerhandwerk]

Guides should live here on nix.dev.

I propose the following structure:

• present a trivial standalone script with non-trivial dependencies

  the example in the Nixpkgs manual using w3m is a good one. it is easy to understand what it does, but shows off why wrapping it in Nix is worthwhile

• show a way to find package names corresponding to the commands used in the script

  Discourse has some examples where this correspondence is non-obvious. including one of them in the script to motivate this step would be great

• wrap the script in a standalone, valid Nix expression

• show how to use the expression in a shell environment (e.g. with buildInputs = [ (pkgs.callPackage ./script.nix) ];)

[fricklerhandwerk]

Closing this since a lot of time has passed. This could still be a guide, and indeed a nice follow-up to the reproducible scripts tutorial where we could take a script and place it into some user environment. But that requires introducing Home Manager and NixOS first. #572