Nix Documentation

349 Members
Discussion about documentation improvements around the Nix ecosystem83 Servers

Load older messages

12 Aug 2022
@Ericson2314:matrix.orgJohn Ericson * doxygen is is per defintion code docs19:27:41
@Ericson2314:matrix.orgJohn Ericsonthere is no good way to get spec prose from that19:27:52
@tpw_rules:matrix.orgtpw_rulesi was thinking more about the literate comment19:29:03
@pennae:matrix.eno.spacepennaeioo putting high-level docs in code is only any good for code bases that are structured like one would tell their story, and nix definitely isn't at this point19:32:25
@denna:matrix.orgolaf John Ericson: i am not opinionated about which repository docs go, as long as they go somewhere for a reason and the reasons gets documented (so we know for the future as well).
The statement that eelco "is anti having reference" is a bit broad.
It seems he believes that the nix documentation should be code reference.
But your work is spec reference. (can i say so?)
@Ericson2314:matrix.orgJohn Ericson olaf: Sure, I would appreciate you seconding me it is spec reference not code reference 22:52:42
@Ericson2314:matrix.orgJohn EricsonAs to the repo, well I am pretty sure bottom half documentation does belong there, not top half documentation22:53:52
@Ericson2314:matrix.orgJohn EricsonI don't think he wants it elsewhere because then any keeping in sync problem would just get worse22:54:16
@Ericson2314:matrix.orgJohn Ericsonand we can't require PRs that add new behavior also update the spec22:54:29
@pennae:matrix.eno.spacepennaehow frequent are such PRs outside of explicitly experimental features?22:59:21
@pennae:matrix.eno.spacepennaefor experimental stuff it's probably okay if well-written documentation lags behind the facts a bit, as long as the necessary information is there somewhere23:00:04
13 Aug 2022
@Ericson2314:matrix.orgJohn Ericson pennae: well most features should be experimental, I have a backlog of a few of them not sure what others got 03:09:00
@Ericson2314:matrix.orgJohn EricsonA space that multiple implementations folllow I understand keeping separate03:09:22
@Ericson2314:matrix.orgJohn EricsonBut I still rather start with that information in the manual03:10:07
@Ericson2314:matrix.orgJohn Ericsonwhile we have the 1 implementation03:10:18
@Ericson2314:matrix.orgJohn EricsonI suppose I would accept making a new nix repo, but then the question comes, what should go in the manual instead?03:11:39
@pennae:matrix.eno.spacepennaeall the more reason to have spec-type documentation separate from the code03:12:12
@Ericson2314:matrix.orgJohn Ericsontop-half docs don't really belong in the manual03:12:21
@Ericson2314:matrix.orgJohn Ericsonif bottom half goes separate too, what's left?03:12:31
@Ericson2314:matrix.orgJohn EricsonJust the literal CLI, config option, etc.?03:12:54
@Ericson2314:matrix.orgJohn EricsonI suppose that (a mostly auto-generated manual) is not the worst03:13:11
@pennae:matrix.eno.spacepennaenot familiar with top/bottom half as terms to describe docs :/03:15:04
@Ericson2314:matrix.orgJohn Ericsonhttps://documentation.divio.com/03:15:24
@yuu:matrix.orgyuu changed their display name from yuu to yuu[m].03:15:41
@pennae:matrix.eno.spacepennaeliterally top and bottom half of that coordinate plane?03:17:22
@Ericson2314:matrix.orgJohn Ericsonyeah03:17:28
@pennae:matrix.eno.spacepennaewould say that the explanations go into the code, the rest goes outside. but obviously haven't read the entire thing so may be misunderstanding the intent03:18:32
* @pennae:matrix.eno.spacepennae better shut up now03:19:41
@yuu:matrix.orgyuu changed their display name from yuu[m] to yuu.05:06:10
@Ericson2314:matrix.orgJohn EricsonSo seeing more progress with Tvix and https://github.com/nix-community/go-nix, I am more willing to have things out of tree12:25:43

There are no newer messages yet.

Back to Room ListRoom Version: 6