| 12 Aug 2022 |
 John Ericson | * doxygen is is per defintion code docs | 19:27:41 |
| John Ericson | there is no good way to get spec prose from that | 19:27:52 |
 tpw_rules | i was thinking more about the literate comment | 19:29:03 |
 pennae | ioo 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 point | 19:32:25 |
 olaf | 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?) | 22:51:26 |
| John Ericson | olaf: Sure, I would appreciate you seconding me it is spec reference not code reference | 22:52:42 |
| John Ericson | As to the repo, well I am pretty sure bottom half documentation does belong there, not top half documentation | 22:53:52 |
| John Ericson | I don't think he wants it elsewhere because then any keeping in sync problem would just get worse | 22:54:16 |
| John Ericson | and we can't require PRs that add new behavior also update the spec | 22:54:29 |
| pennae | how frequent are such PRs outside of explicitly experimental features? | 22:59:21 |
| pennae | for experimental stuff it's probably okay if well-written documentation lags behind the facts a bit, as long as the necessary information is there somewhere | 23:00:04 |
| 13 Aug 2022 |
| John 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 |
| John Ericson | A space that multiple implementations folllow I understand keeping separate | 03:09:22 |
| John Ericson | But I still rather start with that information in the manual | 03:10:07 |
| John Ericson | while we have the 1 implementation | 03:10:18 |
| John Ericson | I 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 | all the more reason to have spec-type documentation separate from the code | 03:12:12 |
| John Ericson | top-half docs don't really belong in the manual | 03:12:21 |
| John Ericson | if bottom half goes separate too, what's left? | 03:12:31 |
| John Ericson | Just the literal CLI, config option, etc.? | 03:12:54 |
| John Ericson | I suppose that (a mostly auto-generated manual) is not the worst | 03:13:11 |
| pennae | not familiar with top/bottom half as terms to describe docs :/ | 03:15:04 |
| John Ericson | https://documentation.divio.com/ | 03:15:24 |
|  yuu changed their display name from yuu to yuu[m]. | 03:15:41 |
| pennae | literally top and bottom half of that coordinate plane? | 03:17:22 |
| John Ericson | yeah | 03:17:28 |
| pennae | would 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 intent | 03:18:32 |
| * pennae better shut up now | 03:19:41 |
| yuu changed their display name from yuu[m] to yuu. | 05:06:10 |
| John Ericson | So seeing more progress with Tvix and https://github.com/nix-community/go-nix, I am more willing to have things out of tree | 12:25:43 |
