| 9 Aug 2023 |
 osslate | Sweet! I'll take a look at this tomorrow | 17:58:34 |
| osslate | Fantastic :) looks like a good time for me, I'll be there! | 17:59:22 |
| 10 Aug 2023 |
| osslate | is nix.dev versioned somehow, to correspond with nixos/nixpkgs channels? | 11:10:50 |
| osslate | This was a consideration I had in writing my own books/docs. Antora seemed like the best toolchain to achieve proper versioning and a toggle to switch, but I decided against it for my personal project as parsing Asciidoc to write automated codeblock testing infra is a pain | 11:13:15 |
| osslate | example: Fedora documentation (Antora based) with a version toggle on the bottom left: https://docs.fedoraproject.org/en-US/fedora/latest/
There appears to be some Sphinx plugins laying around that do something similar, though I haven't tried them myself | 11:20:54 |
 infinisil | osslate: It is not, but I'd be in favor of having that, though because nix.dev can contain content relating to both Nix, Nixpkgs and possibly more, it should maybe somehow expose the versions of all of these orthogonally | 11:22:21 |
| infinisil | Not sure how that should work though, haven't given it a lot of thought | 11:22:31 |
| osslate | Hmmm that's true. It could get messy without proper thought | 11:23:20 |
| osslate | If there's a soup of different versions of different components with content that combines them all, my first reaction would be to version the docs independently... but that introduces its own complexity problems and another layer of versioning | 11:24:19 |
| infinisil | This closely relates to the idea of writing all documentation close to the source, so in Nixpkgs or Nix directly, and nix.dev just collecting all the docs together from all the different repos and rendering them together. Then versioning would become easier because it's clear where a tutorial comes from | 11:24:39 |
| osslate | Oh that's an interesting idea! | 11:27:58 |
| osslate | So some custom-built tooling would git fetch nixpkgs and generate a static website of content taken from there? | 11:29:52 |
| infinisil | osslate: Something like that yeah, for reproducibility it should probably be some JSON lockfile with hashes read by Nix. | 11:39:06 |
| osslate | nice! Sounds like a fun project :) | 11:44:57 |
| osslate | Thinking from a new contributor's POV, my only concern would be barrier to entry depending on how its implemented. Drive-by contributions for docs can be very valuable, and if docs are in a non-traditional docs file structure that requires an amount of nixpkgs knowledge to locate, or potentially breaks the workflow many editors have for following links to other parts of the documentation from one source file, that might work against attracting people to dive in | 12:00:36 |
| osslate | Of course there are some potential mitigations for that: really good first-time contributor docs that allow a person to understand all of that easily, an "edit this page" link that brings someone directly to the nixpkgs docs source, etc. | 12:19:34 |
| osslate | 
Download image.png | 18:30:59 |
| osslate | experimenting with writing some Vale linting rules for nix.dev based on the style guide, would a PR be welcome or are there other tools preferred? | 18:31:14 |
| osslate | 
Download image.png | 18:39:01 |
| osslate | I know Vale has good support for VSCode and CIs at least | 18:39:02 |
 proofconstruction | We haven't really discussed this much but I imagine there's broad support for more automations like this. Today we did look at a couple old PRs, at least one of which was mostly changing line wrapping. Probably make a draft PR to hold commits for this, and we can discuss it there and in future meetings | 18:45:39 |
| osslate | Sounds good :) | 18:46:54 |
| 11 Aug 2023 |
 asymmetric | In reply to @proofconstruction:matrix.org
We haven't really discussed this much but I imagine there's broad support for more automations like this. Today we did look at a couple old PRs, at least one of which was mostly changing line wrapping. Probably make a draft PR to hold commits for this, and we can discuss it there and in future meetings lol can we talk about line wrapping? can someone explain to me why the change in this PR is good, for someone working on the docs?
If I want to change a word mid-sentence, i have so many more words to go through, it just seems inconvenient.
What's the advantage?
| 07:47:21 |
| asymmetric | I know Valentin is a fan | 07:47:33 |
 Minijackson | There's some reasoning explained here: https://sembr.org/, although sembr advocates for more line breaks than one per sentence | 07:48:57 |
| osslate | As a technical writer, I mostly like line breaks because it's a useful visual indicator of "this sentence is too long and hard to follow and should be split up" | 07:54:59 |
| osslate | * As a technical writer, I mostly like line breaks because it's a useful visual indicator of "this sentence is too long and hard to follow and should be split up or rephrased" | 07:55:11 |
