I was skimming the HN thread for Christine Dodrill’s latest Nix post last night (I Was Wrong about Nix | Hacker News) and had a thought while reflecting on some of the difficulties described (which I relate to…):
I wondered if new users would have an easier time finding their sea legs if they could reference a living flowchart (like a differential diagnosis chart?) that maps common problems/goals(/frustrations?) to up-to-date best-practice patterns/tools/options/features across the ecosystem.
It’s secondary, and I’m not sure how to do it intuitively, but there might be additional value in keeping previous-best-practices discoverable (which might help update old patterns, or interpret old posts/answers/repos)?
I don’t imagine this as an FAQ replacement (because its scope should be well defined), but it would certainly fold in how-do-I-X kinds of questions.
If the graph grew dense enough, the reverse might also be helpful: start with a NOUN in the ecosystem, and see the problems/goals/frustrations it addresses.
I jumped into NixOS quite recently, and it was really hard at the beginning, I really struggled with how things are working, how they are put together.
When it came to some basic developer stuff like “How do I setup back my ruby environment” I had the feeling Nix could helped me create a reproducible development environment without using rbenv, etc…, but I could not find how to leverage it. Fortunately, I’ve been helped throughout my journey by people on this discourse, without their help I could have give up.
After a few months (3, in fact) I started understanding how it works (I’m quite a slow learner), made some PR (and managed to make a mistake while doing this by the way). And its only after all this time that I can say I started to understand on how all the things are put together.
There is still a lot of things I didn’t took time to understand correctly (why are overlays better than package overrides, what are Flakes and how can I leverage them, what are the concrete use-cases of both etc…).
If we could lower the learning-curve steep, even just a bit, it would totally worth the effort. Even if understanding more of Nix/NixOS is always rewarding, making that “reward” a bit more accessible could be a huge plus for opening this technology to a bigger audience.
I know people that want to try NixOS, but that are afraid with the complexity. Using a system that is fundamentally different on some basic aspects can be a bit frustrating when you have “muscle memory” on how to setup your favorite development environment for your favorite framework on imperative systems.
TL;DR : The idea behind the living flowchart is really great.
I would love to see and help you build such living flowchart.
I don’t think I have time to drive this any time soon, but I did stumble on a JS library (mermaid) that might be able to handle this. Here’s a live-editor and the flowchart documentation.
I haven’t been able to find something that already combines the flowcharts with the kind of granular interaction/animation model that we’d need to support navigating a really big SVG graph, but the interaction docs at least make me think it could work.
I see two short-term tasks that would help establish whether this is tractable (without, hopefully, getting bogged down in what it should do or how):
a little initial research to answer some open tooling questions, like:
is the syntax tolerable?
are the errors helpful enough that a naive/novice user can debug what they did wrong?
is there a good way (built-in, or bolt-on) to develop branches of the decision tree in separate files and compose them into larger decision trees? (It seems like, eventually, there’ll just be too much mental overhead with a single very large file?) This might have to account for stuff like node namespacing, too?
is there a good way to generate different graphs from the same information? Imagine some examples like:
a general graph oriented around user needs/motivations
an inverted subset of this graph for each nix command, that answers questions like “what can I do with this thing”?
a minimal interaction layer that ensures
we could use mermaid-js to generate a consistently-usable interaction experience
performance doesn’t fall off a cliff at graph sizes too small to plausibly be fit for the purpose
I penciled out some steps beyond this, but doing so made me start to suspect that, if this is viable, it should probably build on or be a component of the documentation-generation builds, especially if the manuals are able to make a leap to RST/Sphinx between now and 20.09.