In a Nixpkgs’ PR, I wanted to explain better the support NixOS has for a certain GNOME feature. I received many review comments from a very competent and appreciated member in our community (also a busy one I think), saying that the NixOS support for this feature could and should be improved.
I agree with the reviewer that improving the interfaces I documented will be beneficial. However, I don’t think that this should hold such a PR from getting accepted. In general, this experience with trying to help documentation feels somewhat familiar and typical in our ecosystem - our ecosystem is not ideal (and it will never be) and when someone opens a simple PR that merely tries to document things a little better, people start talking about how the system should be improved, instead of talking about whether the documentation is good or not.
Sorry, I am indeed busy with a new job. Still need to get back to the dconf PR.
My aversion to such workarounds is somewhat instinctual so it is difficult for me to put it into words but I guess it boils down to the following:
I do not consider the manuals a good place for tricks like that. Manuals should serve as a reference in the diátaxis framework but explaining around insufficient implementation is more of a domain of how-tos. Though I acknowledge the separation is not currently enforced.
Many of the proposed docs expose internal implementation details that people should not rely on. And if they want to use it, they should be aware that they are building on unstable terrain. Documentation goes against that and ossifies the implementation – see also what happened with Flakes.
Having a workaround in official docs can make people more likely to accept the status quo rather than being annoyed to working on a proper fix.
But I will defer to the documentation team since they probably have a clearer vision.
@doronbehar since you explicitly and repeatedly asked for feedback, here’s an attempt at a constructive addition to what @jtojnar wrote:
I also think design flaws, bugs, and workarounds should not be part of reference documentation, but rather captured in issues. What reference documentation can do is show examples of using existing functionality as intended. Sometimes that even helps making a case that the implementation is buggy with respect to that documentation.
How to deal with particular PRs that try to address known problems is largely a cultural issue though, and depends on the code owner. This is a recurrent theme in the ecosystem, and in my opinion, codifying successful patterns that participants agree on helps a lot to resolve ambiguity. We do that in the Nix maintainer team with good results. Oftentimes around Nixpkgs we still don’t have clear code ownership, and that is a wicked problem in itself.
Perhaps what captures better my criticism of this culturally common behavior in Nixpkgs, is the fact that it is not well defined what is considered a “workaround for a bug”, or a “design flaw”, or what is considered “implementation details the user should not be exposed to”. I think that the concept of NixOS modules for instance is unique, and although it exists for years, we are not yet able to make such distinctions, and maybe we shouldn’t.
I reach this conclusion because I see that we treat all module options the same in our docs - all the way from low-level ones such as systemd.services.<name>.unitConfig and environment.etc, to abstract, module specific options. While what most modules do is essentially abstract some of the low-level systemd like module options, to higher level ones.
Hence, I don’t find it so bad to use the manual to instruct e.g how to use environment.etc and other low-level NixOS module options, to achieve a certain feature in NixOS, that is achieved easily in other distributions with a simple imperative apt-get install like command.
Definitely if we had a distinction between diataxis-like documentation, what I tried to propose in PR 240780 would have been added to the “how-to” section. My point though, is that adding such content now, when documentation is not yet divided to diataxis-like sections, doesn’t hurt anyone, and it could be taken to the correct diataxis section later.
