| 12 Aug 2022 |
 John Ericson | (I wrote that in the Nixpkgs arch chanel, but I meant to write that in this channel) | 17:03:02 |
| John Ericson | Based on our call yesterday, I think we all disagree with that? | 17:03:19 |
| John Ericson | so it would be good to do something as a team about that | 17:03:27 |
 tpw_rules | is there a way to automatically extract that stuff into something that's not doxygen? | 19:13:48 |
| John Ericson | tpw_rules: not in a good way | 19:27:28 |
| John Ericson | doxygen is is per defintion code decs | 19:27:39 |
| 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 |
