Nix Documentation - Public Room Timeline

	Nix Documentation	415 Members
	Discussion about documentation improvements around the Nix ecosystem	84 Servers

Load older messages

Sender	Message	Time
10 Aug 2023
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
osslate	In reply to @asymmetric:matrix.dapp.org.uk But the 80 column mark provides an upper bound for sentence length How do you determine the "correct" upper bound for sentence length?	09:14:20
osslate	Documentation isn't poetry 😅 editing is very intuition based (beyond style guides which cover grammar, voice, correct spelling/case for terms)	09:16:47
osslate	Also considering that a defined column length will be inclusive of markup (code segments, bold, italic, etc.) which isn't ideal either	09:19:15
osslate	Contradicting myself here after saying "documentation isn't poetry", but a real metric that can be used is word count in an individual sentence. Column wrapping isn't useful to get that metric, though	09:24:31
infinisil	I've been using the one-sentence-per-line convention for some time now, and I'm a big fan of it.	09:48:37
infinisil	Or, I've become a big fan of it, makes reviews easier and diffs nicer	09:52:16
infinisil	And hints at sentences that could be broken up	09:52:41

Show newer messages

Back to Room ListRoom Version: 6