-
-
Notifications
You must be signed in to change notification settings - Fork 14.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[RFC] Nixpkgs manual structure: visibility of package usage notes #77555
Comments
I wrote some documentation recently and noticed this. Steam and weechat should definitely be moved elsewhere. |
The part Builders describes builder functions as well as packages obtained using some of those functions. I suppose the chapter Packages could become a part Packages. I merged all of it together with as reason basically a comment you made:
|
The part Builders describes builder functions as well as packages obtained using some of those functions. I suppose the chapter Packages could become a part Packages.
That definitely sounds like an improvement.
I merged all of it together with as reason basically a comment you made:
> On the other hand, I think the package notes are a mess right now, as there is no separation between notes of type «this is how you update X.org» and «this is how you use Steam»
I tried to create _some_ separation at least for clear-cut cases with muddy cases getting assigned wherever they felt slightly less mis-fitting. I think we eventually need to have this separation here, so that we can tell the users that one chapter is useful for them even if they are not yet ready to edit non-plain-data Nix expressions.
|
Hello, I'm a bot and I thank you in the name of the community for opening this issue. To help our human contributors focus on the most-relevant reports, I check up on old issues to see if they're still relevant. This issue has had no activity for 180 days, and so I marked it as stale, but you can rest assured it will never be closed by a non-human. The community would appreciate your effort in checking if the issue is still valid. If it isn't, please close it. If the issue persists, and you'd like to remove the stale label, you simply need to leave a comment. Your comment can be as simple as "still important to me". If you'd like it to get more attention, you can ask for help by searching for maintainers and people that previously touched related code and @ mention them in a comment. You can use Git blame or GitHub's web interface on the relevant files to find them. Lastly, you can always ask for help at our Discourse Forum or at #nixos' IRC channel. |
This issue has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2022-10-22-documentation-team-meeting-notes-12-nixcon-edition/22689/1 |
Describe the bug
Currently package usage information such as OpenGL use on non-NixOS is inside «Builders» section.
Additional context
Some parts of Nixpkgs manual are intended for package users, and some for package developers. Right now the parts for package users are inside the section «Builders» even though they provide no information about any kind of builders.
Previously I tried to separate package-specific development notes and package-specific use notes in #60682 and move the use notes higher (as they are more likely to be useful to the first-time manual reader) but apparently the result was not self-evident enough as shown by #71434
Still, I believe that putting subsections on locales or OpenGL or Nginx ETags inside Builders → Packages does not match the top-level header, hurts discoverability and makes the manual less useful.
As I have previously failed to find a good structure for all that, I ask what are the better alternatives.
The text was updated successfully, but these errors were encountered: