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)
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: https://github.com/NixOS/rfcs/pull/72#issuecomment-681138152
I’m frustrated. Sorry, guys! I really like nix, and I’d love to keep on improving it.
About “popular” vs “unpopluar”:
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:
- no line breaks on the docs at 80
- therefore my issues seem out of context cause it’s cumbersome to scroll all along to the right
- while they are not out of context and about as concise as it can get (except kvm issue)
So remains outstanding an answer to https://github.com/NixOS/nixpkgs/issues/96411 - theoretically. If not burnt out by this meta ping-pong already…
Another root cause:
- No convention / tokenization of “result” https://github.com/NixOS/nixpkgs/pull/96421/files
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 https://github.com/NixOS/nixpkgs/pull/96424? (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:
- Some changes you made are questionably helpful. It’s understandable that you may want these changes, but it’s unclear that it helps the community as a whole. For example, is changing ‘result’ to
./resultreally that helpful? It makes a pretty unnecessary assumption of how you’re using the derivation, and writing
./resultis 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.
- You mention:
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 https://github.com/NixOS/nixpkgs/pull/96424#issuecomment-681789123
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 https://github.com/NixOS/rfcs/pull/74
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:
- Dealing with terms that are undefined or unclear. (Like having a ‘technical term roundup’ or something.)
- Having one or two people familiar with Docker help go over the docs and find the mistakes/places where people familiar with Docker would get confused. (Rather than tiny fixes here and there.)
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: https://rstudio.github.io/tufte/
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.