Rejuvenate the todomvc-nix project

Announcements
1

Hi, I just wanted to let you guys know that I refreshed the todomvc-nix project. Take a look at the project here.

Here is some motivation: NumTide - todomvc-nix: One-Stop Solution for Developing Projects Using Nix

3 Likes
2

This is a nice project, I didn’t know it existed. Ideally, I’d like to be able to send a link to this to developer friends that are interested in nix. Currently – constructive criticism time – I don’t think they would be able to understand what the nix files are doing, or what the benefits are. I feel the success metric would be: can someone look at this repo and understand why they’d want to use nix to build their project, and learn how to apply the patterns you used to their own.

Suggestions:

  1. The general structure of the nix files and build needs to be documented in the README, explain why the nix files mostly live in their own directory, why each default file lives in it’s own nix/ sub-directory.
  2. Overlays provided by this package should be explained, probably with a link back to nix docs on what an overlay is.
  3. Every .nix file should be commented. Particularly things that would not be found in the nix documentation itself.
4 Likes
3

Hi, thank you for your feedback, very appreciated it!

The link to overlays explanation lives in repo’s docs/Nix.md docs, but maybe it is not clear. I’ll make it more clear soon.

4

Thank you for showing how to combine numtide/devshell with flakes! :heart:

Just had a look at the docs. To my perception, there seems to be a braoder understanding that those are bad style:

  • “The devShell attribute is self-explanatory”
  • “Simply put”

Good docs avoid any sort of “stance” and purely focus on “value / char”. To your defense, I’ve seen “wordy” things in the nix docs a lot. It’s not good: the state of the world needs improvement. So maybe it’s worth the effort and try to avoid perpetuating that particular doc writing pattern.

2 Likes
5

Hi, Thank you for the input. Is there any good example of how to structuring the docs that you can share? The documentation is the top priority right now, and any feedbacks are welcome.

6

Unfortunately, I can’t point to anything vetted as a positive example right now. Increasing terseness and trying hard to get as less reliant on contextual knowledge as possible might get a long way.

The examples are already very illustrative.

7

You may want to throw in a nix-channel --update for good measure.
You’ll likely want to set a root password for your first boot …
and of course don’t forget to …

How not to do it.

  • “may want” → may I or may I not (want to or not want to) How am I supposed to know what I may want? Gibberish.
  • “for good measure” → non-intelligible slang
  • “you’ll likely want” → inappropriate delegation of responsibility to the reader
  • “and of course don’t forget to” → non-didactic stance in of course (doesn’t introduce value / char but rather reveals a stance of the writer)
1 Like
8

@Rizary I’d like to ask you to consider to extract some of the devshell-specific knowledge encoded in todo-mvc into https://github.com/NixOS/templates . I can imagine it is an even more effective knowledge propagation medium than a mere example: templates over there have a prime slot at the nix show templates cli interface + a variant not objected to by Elco is a heavy trust anchor.

EDIT: There is also https://github.com/nix-community/nix-environments, specifically this issue, which emanted in this discussion and might be an interesting place to help people get started with a (devshell-)project.