| 30 Jul 2023 |
 proofconstruction | genuinely no idea what happened there. i guess i forwarded that message to this channel? finding some rough edges in fluffychat apparently! | 22:41:22 |
| proofconstruction | In reply to @alejandrosame:matrix.org
Hello all! This issue shouldn't be too problematic, but if you have any considerations to improve the exposition I'll appreciate the feedback: https://github.com/NixOS/nixpkgs/issues/246234 this is great - i really like the idea of labeling every (sub)section with the relevant diataxis category as a first step | 22:43:09 |
| proofconstruction | re: the installation guide on the wiki coming up in top search engine results - this is (in my opinion) another great reason to make an actually-official one (wiki.nixos.org?) that still has community-generated content. not really sure what happened historically to yield the present state of affairs, but it's confusing and bad as everyone keeps pointing out | 22:46:20 |
| proofconstruction | that is, community-generated in the sense of not being largely dependent on stewardship by the docs team, which is still under-resourced | 22:47:03 |
| 31 Jul 2023 |
 asymmetric | In reply to @fricklerhandwerk:matrix.org
It seems to mainly hinge on the page size. Good tagging and summaries of smaller pages would surely have positive impact as well. indeed:
- https://pagespeed.web.dev/analysis/https-nixos-org-manual-nixos-stable/0jv7c6prdy?form_factor=desktop
- https://pagespeed.web.dev/analysis/https-nixos-wiki-wiki-NixOS_Installation_Guide/6d6uu0tx4h?form_factor=desktop
| 09:22:57 |
 pennae | looking at the meeting notes; henrik-ch: for which manual are you looking for alternatives? | 15:40:40 |
| pennae | or rather, what's the goal for that manual regardless of tooling | 15:42:13 |
 henrik-ch | Hi pennae , thank you for reaching out - when you read the meeting minutes, you may think that I am doing something or being very concrete about manual rendering alternatives, but that is not the case, rather I am being very unconcrete I would say 😀. | 15:49:05 |
| henrik-ch | What I have seen and been impressed by is https://ryantm.github.io/nixpkgs/ and I took a look to see how it's been rendered, that's all. I am still very much a beginner to all these things. | 15:50:22 |
| pennae | we're just a little confused by the generic "alternative manual rendering" juxtaposed with a "nixpkgs" url. nixos-render-docs is itself an alternative/replacement of mmdoc because mmdoc is such a nightmare to extend | 15:50:58 |
| henrik-ch | In reply to @pennae:matrix.eno.space
we're just a little confused by the generic "alternative manual rendering" juxtaposed with a "nixpkgs" url. nixos-render-docs is itself an alternative/replacement of mmdoc because mmdoc is such a nightmare to extend You clearly know a lot more about this topic than I do! I am sorry if the statements caused confusion or concern. | 15:52:04 |
| pennae | we're happy to explain if you have any questions | 15:53:39 |
 ryantm | What is "such a nightmare to extend" based upon? | 17:34:54 |
| ryantm | Is merely using C as the implementation language enough to brand it as such? | 17:35:27 |
| pennae | personal experience; we tried to add an extension (forget which one it was, unfortunately) and just gave up after a while because it kept segfaulting and misbehaving in other ways :/ | 17:55:23 |
| pennae | you did an amazing job getting it as far as it is, but that experience and the many pitfalls of complex software written in C have us worry that it won't be very maintainable by anyone except you | 17:57:08 |
| ryantm | Alright, well I'm still actively working on improving it, so if you have feature requests I'd be interested in hearing them. | 20:03:12 |
| pennae | currently there's nothing pressing since nixos-render-docs has kind of become the renderer for nixpkgs/nixos 😶 | 20:05:09 |
| pennae | we're not attached to the tool at all, if you can do better with mmdoc then by all means go for it | 20:07:13 |
| pennae | but maintainability is a concern we have, and python does tend to be easier on contributors than C | 20:08:11 |
| 1 Aug 2023 |
|  Charles changed their profile picture. | 01:12:22 |
 fricklerhandwerk | In reply to @pennae:matrix.eno.space
but maintainability is a concern we have, and python does tend to be easier on contributors than C I second that. From everyone I read of or talked to about documentation (I’m mainly in touch with a bunch of Haskellers) I got convinced we should put extraordinary emphasis on low tech tooling, meaning they should be easily accessible to the average user. Python ans Markdown fit the bill better than, say, C and ReST | 08:33:21 |
 RÃgille S. B. Menezes | Hey I'm new here, just wanted to share this because I think giving more emphasis on this tip would be a good idea in the documentation
https://twitter.com/sullyj3/status/1686231703445221377 | 13:29:32 |
| asymmetric | In reply to @rigille:matrix.org
Hey I'm new here, just wanted to share this because I think giving more emphasis on this tip would be a good idea in the documentation
https://twitter.com/sullyj3/status/1686231703445221377 hey, welcome! That command is marked as experimental, and as such it is currently out of scope for nix.dev | 13:34:05 |
| RÃgille S. B. Menezes | Oh I see | 13:36:50 |
| 2 Aug 2023 |
 infinisil | This is still a draft PR and not done, but it could already use some feedback, best reviewed commit-by-commit, with most commits just moving things around, only some add new content: https://github.com/NixOS/nixpkgs/pull/245243 | 22:41:38 |
| infinisil | I'd also like to discuss it briefly in this Thursday's docs team meeting | 22:42:17 |
|  @adam:robins.wtf joined the room. | 23:41:48 |
|  @adam:valkor.net left the room. | 23:41:52 |
| 3 Aug 2023 |
| asymmetric | I 90% won’t make it to todays doc-comments RFC meeting unfortunately cc Johannes Kirschbauer @hsjobeki | 09:21:58 |
