Nix Documentation - Public Room Timeline

	Nix Documentation	421 Members
	Discussion about documentation improvements around the Nix ecosystem	83 Servers

Load older messages

Sender	Message	Time
10 Aug 2023
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
asymmetric	just to be clear: i'm arguing for soft line breaks (a newline inserted by the editor) at some arbitrary column, say 80	07:55:49
Minijackson	In reply to @asymmetric:matrix.dapp.org.uk just to be clear: i'm arguing for soft line breaks (a newline inserted by the editor) at some arbitrary column, say 80 I've done that for quite some time, but I found that diffs becomes unreadable, which is an issue for PRs that needs to be reviewed	07:58:38
asymmetric	In reply to @Minijackson:matrix.org I've done that for quite some time, but I found that diffs becomes unreadable, which is an issue for PRs that needs to be reviewed do you have an example? or how do they become unreadable?	07:59:39
asymmetric	In reply to @Minijackson:matrix.org I've done that for quite some time, but I found that diffs becomes unreadable, which is an issue for PRs that needs to be reviewed * do you have an example? or could you explain how they become unreadable?	07:59:52
Minijackson	there's some example here: https://rhodesmill.org/brandon/2012/one-sentence-per-line/	08:02:46
Minijackson	`-The beauteous scheme is that now, if you change -your mind about what a paragraph should look -like, you can change the formatted output merely -by changing the definition of ‘‘.PP’’ and -re-running the formatter. +The beauty of this scheme is that now, if you +change your mind about what a paragraph should +look like, you can change the formatted output +merely by changing the definition of ‘‘.PP’’ +and re-running the formatter.`	08:02:58
Minijackson	* there's an example here: https://rhodesmill.org/brandon/2012/one-sentence-per-line/	08:03:44
osslate	I liken it to: imagine a program written in something like Nix or C. Now, imagine instead of one statement per line, the entire program was smushed together, with newlines only occurring at the 80 col mark. ...now, imagine receiving a substantial PR to change something in that spaghetti :D	08:04:37
alejandrosame	infinisil: I'm already part of `NixOS/nixpkgs-maintainers` -> https://discourse.nixos.org/t/join-the-package-maintainer-team/3751/68?u=alejandrosame	08:38:03
asymmetric	In reply to @osslate:fsfe.org I liken it to: imagine a program written in something like Nix or C. Now, imagine instead of one statement per line, the entire program was smushed together, with newlines only occurring at the 80 col mark. ...now, imagine receiving a substantial PR to change something in that spaghetti :D I’m not saying new lines should only be at the 80 column mark, people are free to break after each sentence according to semantics, presentation, etc	09:09:56
asymmetric	But the 80 column mark provides an upper bound for sentence length	09:10:24

Show newer messages

Back to Room ListRoom Version: 6