I must admit that their documentation & posts comes off very polished.
I’m not sure why I feel that way vs Nix documentation.
I’m saying that to drive constructive feedback and to be clear I absolutely am a big fan of NixOS.
How I see it, this can be explained by multiple reasons.
The Nix project is larger, which makes it harder to coordinate. It’s more like a bazaar where you get to pick the Nth implementation of npm2nix. Eventually, we will get there in a more organic fashion.
In terms of leadership, I think that Ludociv is more vocal about the directions of the Guix project, which helps pull people together. Eelco is mostly focused on building the tooling, and then lets the community organize themselves.
The last factor that I can think of is the DocBook horror show that we have long suffered from. Hopefully, when that gets switched to Markdown it will be easier to contribute to the docs.
Changing any of these things is quite challenging as they are so deeply ingrained. But I am confident that we will get there. Sometimes it takes a single person to decide to take things at heart and tackle a specific problem.
I looked into contributing to the Nixpkgs documentation, especially on adding new toolchains, but ran into DocBook. Is there a markdown translation in the works? Perhaps pandoc can automate large parts of the work.
Agreed, I closed one of my almost finished PRs because I really disliked the tag soup which is docbook https://github.com/NixOS/nixpkgs/pull/103506. I’m sure that docbook is a really powerful tool. But the learning curve is way steeper than I care for, documentation should be easy to modify, and docbook is not. Especially if you’re not familiar with it. With commonmark, you can easy find an example of a section, header, paragraph, a list, and a code block, and you’ve got 90% of your documentation tooling learned. Meanwhile, docbook has 60 different types of lists https://tdg.docbook.org/tdg/4.5/listitem.html
RFC was merged, not sure where we go from there.
Regarding the Nix/Nixpkgs/NixOS documentation, I am comfortable with topic-oriented guides but confused a bit with the manual. The description of each section is fine but there seems some room for improvement in the ordering and such IMHO. All-in-one format is questionable too, as, when I am aware that where is the relevant information, loading the whole manual is a waste of time and network.
To be honest though, the act of adding documentation was still pretty high given there’s a lot of subjective criticism over style. I almost gave up on that PR since it took so many drafts… although I guess at the end I’m thankful for @doronbehar feedback because it did really make the documentation good , clear & concise.
I really dislike the single page nature of nixpkgs & nixos documentation.
Following anchor links are so slow to load; having a sidebar view similar to Rust’s would be awesome.
Agreed. The way GNU does it is also acceptable, though mdbook would be nicer. https://www.gnu.org/software/emacs/manual/emacs.html
A sort of document maintainer/shepherd-like role might be nice for more deterministic and streamlined (? I may choose wrong words; I mean, as little I’m tired a bit since it seems endless moment as possible) process.
Also, some specific documents like change logs might be better to use one-file-per-topic fashion (with some pre/post-processes if needed) to reduce merge conflicts.
This seems to be it.
I love clojure nrepl emacs cider & nix, Two years ago, before I started working on nixos, I’ve installed guix a few times. Back then, I didn’t really know what this system was. Now know because of nix. I got to know what guix is. so anyway I’ve been looking to learn the guile scheme.
we look forward to interop of guix and nix. (example of https://github.com/talyz/fromElisp … so fromClojure) The reason is that I want haskel and purescript to be linked with nix/guix repl. hehe (nice nix/guix world)