| 30 Jul 2023 |
 asymmetric | Is the SE placement of the manuals something that the marketing team needs to work on (as in SEO), or is it dependent on us, for example by splitting the manual to reduce page load? | 16:43:47 |
 alejandrosame | 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 | 18:55:07 |
|  Austin Horstman joined the room. | 20:03:38 |
| Austin Horstman changed their display name from Austin Horstman to Khaneliman. | 20:09:56 |
| Austin Horstman set a profile picture. | 20:12:06 |
 fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
Is the SE placement of the manuals something that the marketing team needs to work on (as in SEO), or is it dependent on us, for example by splitting the manual to reduce page load? It seems to mainly hinge on the page size. Good tagging and summaries of smaller pages would surely have positive impact as well. | 21:26:43 |
 proofconstruction | In reply to @asymmetric:matrix.dapp.org.uk
Is the SE placement of the manuals something that the marketing team needs to work on (as in SEO), or is it dependent on us, for example by splitting the manual to reduce page load? It seems to mainly hinge on the page size. Good tagging and summaries of smaller pages would surely have positive impact as well. | 22:40:52 |
| 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 |
