| 8 Nov 2023 |
 fricklerhandwerk | In reply to @infinisil:matrix.org
It's a bit non-standard, but it seems fine We could iterate on it | 07:38:23 |
| 9 Nov 2023 |
 raboof | do we have any doc writing guidelines such as "try to avoid words like 'simply'"? | 09:10:41 |
| fricklerhandwerk | In reply to @raboof:matrix.org
do we have any doc writing guidelines such as "try to avoid words like 'simply'"? Whe have a style guide for nix.dev https://nix.dev/contributing/documentation/style-guide
but no specific note on “simply”. | 09:33:34 |
 asymmetric | In reply to @raboof:matrix.org
do we have any doc writing guidelines such as "try to avoid words like 'simply'"? what's your beef with "simply"? 😃 | 09:50:15 |
| raboof | in short, documentation is almost always better without it: it is typically added to encourage the reader, but often has the opposite effect and may even appear condescending, especially when the reader runs into trouble trying to apply the suggestions from the documentation. Best-case it's mostly just noise. I'm sure others have motivated this better than I can in a few sentences though, I can see if I can dig up any good references later - first wanted to see if we had any already. | 09:55:08 |
| fricklerhandwerk | In short: what’s simple for you may be impossible for others. Avoiding that is in line with our stance not to assume things about the reader | 10:03:08 |
| fricklerhandwerk | * In short: what’s simple for you may be impossible for others. Avoiding that is in line with our stance not to assume things about the reader and not making value judgements | 10:03:38 |
| fricklerhandwerk | That’s why for instance in reviews I always suggest alternatives to “as you can see…” or “you will see an output…” – no, not everyone can see. | 10:05:55 |
| fricklerhandwerk | There are entire software companies full of people who can’t see. | 10:07:28 |
| asymmetric | My pet peeve is "trivial" 😂 | 10:45:38 |
| fricklerhandwerk | “Left as an exercise for the reader” | 11:20:52 |
 infinisil | Also "just" can have that meaning! | 11:41:24 |
| asymmetric | https://githubnext.com/projects/copilot-for-docs/ | 11:54:46 |
| asymmetric | is openai gonna write docs for us now? | 11:56:50 |
|  Alexandro de Oliveira joined the room. | 12:28:58 |
| fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
is openai gonna write docs for us now?
if we can answer most of developers’ questions directly from the code, we can learn what questions are still unanswered and “interview” maintainers. Instead of writing whole docsets, maintainers are prompted to write one paragraph at a time.
Hm, I don't need AI for that
| 12:57:03 |
 henrik-ch | Won't make the doc call today, sorry! | 14:34:42 |
| asymmetric | hadn't deployment of pr been fixed by delroth? | 16:21:08 |
| asymmetric | * hadn't deployment of nix.dev prs been fixed by delroth? | 16:21:13 |
| asymmetric | or am i misremembering? | 16:21:26 |
| asymmetric | huh interesting, infinisil's latest commit was deployed, but is marked as "inactive" https://github.com/NixOS/nix.dev/pull/645 | 16:22:12 |
| asymmetric | oh i see, it's because another pr was deployed in the meantime | 16:23:04 |
| asymmetric | then i don't know if this integration with github deployments is very useful, since it only keeps one deployment active: https://github.com/NixOS/nix.dev/deployments/pull%20request | 16:24:06 |
| asymmetric | whereas the action simply posts a message in a pr with a per-pr deployment | 16:24:51 |
| 10 Nov 2023 |
| infinisil | Oh yeah those deployments aren't very practical for this purpose.. | 03:49:41 |
|  @atka:matrix.org left the room. | 07:35:22 |
|  @harsh-ps-2003-63ce2d0d6da0373984bd6022:gitter.im joined the room. | 11:23:43 |
| asymmetric | Style question: do we capitalize every (important) word in titles, or just the first? | 12:46:16 |
| fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
Style question: do we capitalize every (important) word in titles, or just the first? Statistically speaking only the first. The reason is because I find that saner than learning rules that don’t apply for any other parts of the text, and I merged a lot of stuff. Would help to add that to the style guide. | 12:49:59 |
| fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
Style question: do we capitalize every (important) word in titles, or just the first? * Statistically speaking only the first. The reason is because I find that saner than learning rules that don’t apply for any other parts of the text, and I merged a lot of stuff. Would help to add that to the style guide if we agree on it. | 12:50:29 |
