| 18 Jan 2024 |
 @johannes.kirschbauer:scs.ems.host | I'd like us to attach doc-comments to every user accessible function in nixpkgs. At least the important ones.
But that might require a shift in the mental model, how we write documentation.
Should I join the documentation team, and take some part of the ownership of the nixpkgs reference manual? | 19:13:02 |
| @johannes.kirschbauer:scs.ems.host | * Hey, every piece of help is very valuable ;)
Programming stuff where i could need help:
- https://github.com/NixOS/nixpkgs/pull/262987
- Extend the current python rendering: https://github.com/NixOS/nixpkgs/pull/281212
- https://github.com/nix-community/nixdoc/pull/91
Documentation stuff:
- Write: Just visit noogle.dev and pick a random function that is not documented. Place a doc-comment (see rfc145) at the position that noogle gives you. (Sometimes position tracking doesn't work yet, especially for functors.)
- Extend the scope: danielsidhion: https://github.com/nix-community/noogle/pull/68. Once the CI finishes: https://noogle.dev/f/pkgs/appimageTools/wrapAppImage should display your wrapAppImage content. Unfortunately there is nothing documented ;)
Thanks. I am always looking to extend the scope of Noogle.
If we use the current toolset that i have as a benchmark. Given the 1.6k noogle discovered functions the answer currently is somewhat ~95%. Maybe we can get better, but we have to understand some more edge cases. A correct position tracking is Key to finding the doc-comments.
In the future this may become part of native nix, but thats a long way to go. And I currently focus on building incrementally better tools, until all questions are resolved and either I or somebody else volunteers to integrate that into nix natively.
| 19:24:50 |
 danielsidhion | I'd love for us to document most stuff in the code directly and have it show up in the manual, but we'll have to figure out a lot of small details. Currently I'm working on the other end (adding/updating content to the manual and finding a good common structure for everything) and I have a wishlist of things I'd like to see in tooling that generates the docs | 19:25:38 |
| danielsidhion | If you're interested in that, I can start a list so we can start figuring out work that needs to be done until we finally merge both efforts | 19:27:24 |
| @johannes.kirschbauer:scs.ems.host | I'd really appreciate if we can work together. I also have some visions and ideas how stuff could work out nicely. | 19:28:24 |
| @johannes.kirschbauer:scs.ems.host | danielsidhion: I'd be interested if we could meet and present both our lists of stuff and maybe figure out a rough roadmap. (I'll have to prepare mine tho) | 19:30:28 |
| danielsidhion | Neat, I like this idea. I'll ping you when I have my list (might take a few days, my availability will be reduced until next ~tuesday) and then we can chat once w | 19:31:23 |
| danielsidhion | * Neat, I like this idea. I'll ping you when I have my list (might take a few days, my availability will be reduced until next ~tuesday) and then we can chat once we're ready | 19:31:30 |
 @philipp:xndr.de | If you want me to, I'll join. I should be able to get somewhat up to speed till then and will just document a few functions in the meantime. | 20:26:18 |
| 19 Jan 2024 |
 fricklerhandwerk | I’d strongly support Johannes Kirschbauer @hsjobeki and danielsidhion taking ownership of Nixpkgs documentation! | 00:09:58 |
|  @ThorHop:matrix.org changed their display name from hopland (meticulous montesquieu) to hopland (manners or stfu). | 05:12:15 |
| @ThorHop:matrix.org changed their display name from hopland (manners or stfu) to hopland. | 05:14:40 |
| @philipp:xndr.de | I started to document wrapAppImage and I think I've found a few fault points that I'd like to discuss on Tuesday. | 14:57:49 |
| 20 Jan 2024 |
|  ris_ joined the room. | 12:36:32 |
| ris_ | https://github.com/NixOS/nixpkgs/pull/273840 hard to get people to review documentation PRs isn't it? ;) | 12:37:07 |
| ris_ | oh balls it has a merge conflict | 12:37:26 |
| ris_ | just a sec | 12:37:31 |
| ris_ | ok fixed | 12:42:52 |
 infinisil | ris_: Merged! | 21:39:44 |
| 22 Jan 2024 |
| @johannes.kirschbauer:scs.ems.host | danielsidhion: philipp I pm ed you, lets schedule our meet! Once we find a suitable schedule we'd announce it if anyone else wants to join. | 11:41:25 |
| @ThorHop:matrix.org changed their display name from hopland to IdeallyYes. | 15:06:13 |
|  SYMYƧ joined the room. | 23:11:44 |
| SYMYƧ | Would this be the right place to provide feedback on nix-pills? It's the closest I've found so far. My complaint is that Chapter 2 could use a lot of improvement. It's missing a lot of context needed to make it understandable to the target audience, and this is a problem considering it's the first true "meaty" chapter (chapter 1 being a justification of why you should use Nix at all). | 23:17:16 |
| SYMYƧ | I also don't entirely understand the history and context of the guide itself. I find it's being suggested as the de-facto standard for learning how to write derivations. Yet, it reads as though it was the work of a single author. Is nix-pills an "official" document that is community maintained? That's kind of how I've been treating it in suggesting improvements, because I've seen it presented as this de-facto standard. | 23:21:37 |
| 23 Jan 2024 |
| infinisil | symys: The nix pills live in the official GitHub organisation, so they're official: https://github.com/NixOS/nix-pills | 01:06:33 |
| infinisil | I personally don't think they're as useful as they're made out to be, and would favor deprecating them | 01:07:33 |
| infinisil | The documentation team is focusing on https://nix.dev/ as the way forward (also official) | 01:07:57 |
| infinisil | Despite that, the nix pills are still somewhat maintained, so if you make a PR, the docs team could review and merge that :) | 01:09:29 |
|  efx changed their display name from efx to Eli Flanagan. | 17:59:28 |
| efx changed their display name from Eli Flanagan to efx. | 18:00:40 |
