Skip to content
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

Open
7c6f434c opened this issue Jan 12, 2020 · 5 comments
Open

[RFC] Nixpkgs manual structure: visibility of package usage notes #77555

7c6f434c opened this issue Jan 12, 2020 · 5 comments
Labels

Comments

@7c6f434c
Copy link
Member

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.

@7c6f434c 7c6f434c added the 0.kind: bug Something is broken label Jan 12, 2020
@rnhmjoj
Copy link
Contributor

rnhmjoj commented Jan 12, 2020

Currently package usage information such as OpenGL use on non-NixOS is inside «Builders» section.

I wrote some documentation recently and noticed this. Steam and weechat should definitely be moved elsewhere.

@FRidh
Copy link
Member

FRidh commented Jan 14, 2020

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:

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»

@7c6f434c
Copy link
Member Author

7c6f434c commented Jan 14, 2020 via email

@stale
Copy link

stale bot commented Jul 13, 2020

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.

@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jul 13, 2020
@nixos-discourse
Copy link

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

@stale stale bot removed the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Oct 22, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

4 participants