Please can somebody give answers to those questions, so I can submit PRs to improve the docs as @worldofpeace suggested?
https://github.com/NixOS/nixpkgs/issues/96406
https://github.com/NixOS/nixpkgs/issues/96408
https://github.com/NixOS/nixpkgs/issues/96410
https://github.com/NixOS/nixpkgs/issues/96411
https://github.com/NixOS/nixpkgs/issues/96412
https://github.com/NixOS/nixpkgs/issues/96413
Hi,
Iāll reply here with what I was about to say on the issue tracker.
I would need clarification about those imprecisions first. But rather than having a meta discussion, letās just fix the source quickly and efficiently.
The clarifications are part of the meta discussion that is necessary to ājust fix the source quicklyā.
Before looking into the questions, let me preface that the manner in which the issues were opened, one issue per line, with context-less questions seem, to my eyes, a bit rude. Though I can see how one might disagree with that.
It would have been better to open one issue with all problems about this section of the documentation combined, considering three of the six are, AFAIK, answered by the same answer. Or even better, start with the questions here, on the Discourse, where support questions are better suited.
Now continuing with some answers. The manuals are reference manuals, so they are written with keeping in mind that the reader has familiarity and knowledge with the material external to the topic. E.g. familiarity with Docker, its tooling, virtualization, and more importantly, familiarity with Nix and the other parts its ecosystem.
Another of the problem seems to stem from lack of familiarity with the Nix ecosystem. The word result within the ecosystem heavily implies the result of building a derivation. Often literally the result symlink from a nix-build. As for a closure, the result of the build of a derivation, and all of the paths it depends on is a closure. (Strangely, the term seems to not be defined in the Nix manual. Though, it wouldnāt be something that is defined in the dockerTools documentation.)
Now, about the kvm device? Itās the kvm device, as provided by the kernel, when hardware virtualization is enabled, more often than not named /dev/kvmā¦ There is some implied background knowledge about /dev/kvm and Nix.
Finally, the three questions that refer to layers, I guess here docker knowledge helps, but really some background details on the implementation should help. Though I wonder if the documentation could help explain better how the layers end up being built.
Finally, I donāt want to sound rude, or to accidentally act as a gatekeeper by saying āget goodā, or anything of the sort. What I want to be understood is that there is a place to ask questions, and here, on the Discourse, is the proper place.
Keep on learning about Nix, Nixpkgs and NixOS, it all is worth it in the end, in case you still had doubts!
OK, letās leave those issues closed then. Iām really, really sorry for all the nuisance and distraction.
I really just need spot-on specifics about those words of those issues.
If that should ever happen, Iām feeling bound by my commitment to open a PR with improvements (though not indefinitely)
Iām committed.
But why is it so hard to produce some simple docs improvements with some minimal 3 liner github issues quickly? (letās exempt the KVM question, this has indeed more meta and is the weakest)
BTW the root cause is that the literal kvm is not properly shown on the docs stylesheet. Would that have been the case - or would it have been written /dev/kvm it would have been less daringly imprecise - being identifiable as a token reference (I only discovered when was looking at the source code, hey thatās some nuisance!).
Letās pray for quick RFC72 implementation!!!
Can one spot its a literal? - only if oneās got photographic memory, enough to spot monotype deviances on a three letter token.
Another root-root-root-rooooot 
cause: [RFC 0072] Switch to CommonMark for documentation by mboes Ā· Pull Request #72 Ā· NixOS/rfcs Ā· GitHub
Iām frustrated. Sorry, guys! I really like nix, and Iād love to keep on improving it.
About āpopularā vs āunpopluarā:
https://grahamc.com/blog/nix-and-layered-docker-images
My prioritization algorithm is a simple graph-based popularity contest. The idea is to weight each node more heavily the deeper and more references they have.
This is getting too disconnected from the sourceā¦ it would have been better to have this discussions on the github issuesā¦ Result now: nothing is going to happen out of this discussion.
Iām tearing my hairs out of my head now that we have valuable information dug into this discourse thread, pushed away from the workflow that would have improved the docs for everyone. aahahahah (sorry, Iām going to āgo goodā soon again)
Another presumable root-root-root-root-root-root cause why you guys suggest to have the discussion over here (which is a bad idea): there are too many open unattended github issues. (Not blaiming, just thinking loud why this happens)
Another root cause:
So remains outstanding an answer to Docs: dockerTools Ā· Issue #96411 Ā· NixOS/nixpkgs Ā· GitHub - theoretically. If not burnt out by this meta ping-pong alreadyā¦
Another root cause:
Please calm down. These rants here, in issues, or in RFC pull requests are not helping anyone including yourself .
Make a list of questions you have. Once the list is done, ask the questions here in a single Discourse post. You will get helpful answers (as most questions on this Discourse).
Think about how the documentation can be clarified such that it would have answered your questions. In some cases a cross-reference to another part of the manual would be enough. Make these changes and do a pull request.
I know everyone hates DocBook. And DocBook makes drive-by contributions hard. But it is not that difficult to contribute some changes to some existing DocBook documentation. I hadnāt used DocBook for more than 10 years and a few weeks ago I added a new chapter to the NixOS manual. 95% of the time was spent on formulating the text (which can be hard for a non-native speaker) and perhaps 5% on how do I do this or that with DocBook.
tl;dr: the most productive way of moving the Nix ecosystem forward is by doing.
You are right. Could we merge doc: fix wording on dockertools by blaggacao Ā· Pull Request #96424 Ā· NixOS/nixpkgs Ā· GitHub? (step by step)
Though, robust words sometimes pierce better through first lines of defense, especially if they tell a pain a human being is feeling vividly.
While I understand that you may be frustrated by the wording, I donāt think itās really that helpful making all these minor changes one by one. I think a better way would be to have a discussion generally first, to get you to be familiar with the stuff you want better explained, then we can formulate a better way to express all the things (so for example, what exactly goes to dockerTools docs, what goes elsewhere, how to deal with words etc.)
Two problems have already manifested with your approach:
./result really that helpful? It makes a pretty unnecessary assumption of how youāre using the derivation, and writing ./result is really going to be helpful as an example in commands, where itās relatively easy to eyeball substitute it for ābuild resultā. Otherwise, Iād say casually mentioning āresultā is perfectly fine as an English word. As said, these are some things that really could be better done through discussion.Iād say, itās exactly the reason you should calm down and talk first. If your issues and pull requests are driven by emotion itās not going to turn out well.
Some changes you made are questionably helpful.
OK, I closed the PR doc: fix wording on dockertools by blaggacao Ā· Pull Request #96424 Ā· NixOS/nixpkgs Ā· GitHub
Trying to do small, incremental improvements is too controversial for my taste. I just wanted to help a copy of my future self, but this is going out of balance even for my strongly altruistic sentiments towards being generally helpful.
Iām desisting deliberately from this one.
Ceterum censeo: We should have left the focused discussion on the github issues - one at a time.
I might try again to do good on yet another subject, differently, next time.
Btw, this thread - and in big part me slipping over several bananas - calls out for the spirit of [RFC 0074] Community Coordination Hub by blaggacao Ā· Pull Request #74 Ā· NixOS/rfcs Ā· GitHub
I agree with what you said, but not what you have done. To me, those individual issues are on such tiny points that they end up being quite unfocused. As of how you, I think for example more appropriate things to discuss are:
I understand that you want to help, so Iām also hoping that weāre communicating well as a community when problems occur.
Iām getting deeper into this. I think it would make most sense to wait for RFC72, let it settle, then come up with a proposal for a visual right margin with contextual links (āfurther infoā / āsee alsoā).
Similar to: A Tufte Handout Example
Then start spreading blog-posts / talks all around the docs to satisfy the missing interpretation context and alleviating the burden on authors to be more concise and accurate.