[Help] On creating a nix-book

Development Documentation
1

@nrdxp and I Created https://github.com/divnix/nix-book a year ago. Development stopped for a few months as both of us were pre-occupied with release-management and later life events.

Recently I started contributing to it again, and have fleshed out some introductory lessons on derivations, the nix language, and building a C application.

Call-to-Arms

I’m asking for people to help with editing, refinements, and clarification of the materials.
I’m very bad at prose, and writing long form documentation is definitely outside of my wheelhouse.

Whats the goal of Nix-book

To eventually be the nix equivalent of the rust-lang book. I would really like to have one canonical resource to point individuals wanting to learn more about Nix, and allowing them to at least have an intuition about how certain things in various nix ecosystems fit together.

The main thing which I think a lot of people struggle with nix is how to initially conceptualize what is going on. A lot of blog posts and resources are kind of “media res” (in the middle) of explaining anything, but there’s not much which starts from ground 0 besides the nix-pills series.

Why isn’t nix-pills good enough?

Nix-pills is good if you’re already familiar with nix. I think of it more like the rust-nomicon, where it explores in much greater detail much of nix + nixpkgs implementation details. Although this is great knowledge for someone wanting to become an expert in nix, I don’t think it’s a great introductory resource to someone who wants to “pick up” nix.

Also, I’m a big fan of md-book’s default being a Table of Contents on the left hand side, and people are able to quickly re-visit a particular section.

Rendered book: https://book.divnix.com/
GitHub repo: https://github.com/divnix/nix-book

I haven’t formally asked @nrdxp but, I’m sure he is more than willing to put this under nix-community or nixos organization if asked. The goal was to enable more people to pick up nix. divnix was convenient as we could immediately start working on it.

8 Likes
2

That’s a great project, but wouldn’t this fragment the documentation even more?

3

This fills a different role than the existing documentation, as I understand it. What’s out there is mostly either reference material, like the nix/nixpkgs/nixos manuals, or how-to, like the wiki. We’re missing a decent “overview and foundational concepts”-style documentation that’s approachable for someone first entering into the nix ecosystem.

3 Likes
4

Do you mean Tutorials following Diátaxis framework?

3 Likes
5

Roughly yes, though I wasn’t thinking in precisely those terms.

6

No, the manuals will still be the best for reference documentation. The wiki will still be the best place for very specific topics. Discourse is still the best place for discussion. And Nix-pills will always be a very comprehensive tutorial.

I just want something for that 20-80 pay off. 20% of the potential knowledge, that you’ll use 80% of the time. Nix-pills can fill in another ~50%, and nix+nixpkgs will probably have 30% of it’s domain forever in undocumented source code :).

5 Likes
7

@juaningan do you know if documentation.divio.com is a shameless rip of diataxis or vice-versa or there isn’t any shamelessness involved?

8

It looks for me that divio are using Diátaxis framework without mentioning it explicitly.

Diátaxis have a git repo and known author. Also divio appears in Who’s using Diátaxis? page.

2 Likes
9

I have (some) skill at this, and certainly appreciate the mission!

What form would contributions take? Ordinary pull requests against the book repo?

1 Like
10

Yes, if there’s a section which has been written, then any corrections, improvements, or issues would be helpful :slight_smile:

1 Like
11

This, I can manage! :slight_smile: