Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki
Set by [Coke] on 23 May 2022.
08:02 sena_kun joined 08:46 sena_kun left
ab5tract I expect this has been discussed before, but what about having release-targeted documentation? Similar to how many other projects do it, with a dropdown for selecting the relevant release 10:55
This would free us from having to inline exceptions like “prior to 2022.10” or “after 2023.03” 10:56
patrickb ab5tract: That's a discussion with a long history. I think there is a problem-solving for this. 11:38
ab5tract I figured so :) 11:46
I’ll look it up, thanks!
lizmat if I remember correctly, the consensus was to put in inline exceptions until we have a better solution 11:59
and we don't have a better solution yet
[Coke] release-targeted documention is not feasible with our documentation staffing level. 13:34
but it would be nice, and the manual comments at least are saving the information somewhere. 13:35
there are doc issues for this, you don't need a PS issue 13:36
one moment.
github.com/Raku/doc/discussions/4206
Having just tried to re-catch-up there... it's kind of a mess of threads. 13:38
If you would rather start a new discussion, I would not object. ;)
er, :)
14:06 sena_kun joined
ab5tract Wow, that’s so much more complex than what I had imagined. 15:07
My approach would be simply to generate docs based on bit tags that are keyed to language releases 15:08
s/bit/git/ 15:09
Generate a new static edition every release
And allow these editions to be selected with a dropdown (or changing a sub path in the url) 15:10
No need to annotate anything about this version or that version outside of deprecations and the like, which are then updated/removed in later documentation versions 15:13
As necessary
[Coke] language release or compiler release? 15:22
because the way we do compiler releases, language releases are not fine grained enough. 15:23
we'd still need "ok, 6.d works this way, expect before 2023.08, when..."
s/expect/except/
ab5tract ah, yeah, I meant the monthly releases 15:25
fwiw I would like to revisit the whole language release concept as well, but that's for a different time 15:26
for sure my proposal only works when keying doc releases to language releases 15:28
note that nothing has to have technically changed in the docs between the two tags
the one issue with this is that clarifications and expansions would not be visible in releases prior to their addition 15:29
but I think that is a deeply normal way for documentation to work :)
[Coke] I think compiler release is too fine grained for that, but language release makes sense. 15:34
we already have years of "hey this changed in this compiler release" that are NOT reflected in the docs today
so it's not just a matter of changing how we present the docs: we don't *have* those docs.
... which reminds me, I didn't create the tickets to grab the last few releases of changes for docs. 15:35
github.com/Raku/doc/labels/checklist
We basically don't have anyone writing docs right now. We have fin*, who is more website/rakudoc, coleman who is infra, and me who is more like a PM with no one to M. :) 15:38
[Coke] will resolve to get those missing checklist items in the tracker today.
so, not telling you "no", just explaining why things are the way they are right now 15:39
thank you for your interest in docs.
ab5tract > 5:23 PM <[Coke]> because the way we do compiler releases, language releases are not fine grained enough. 15:40
That seems to contradict: 15:41
> 5:34 PM <[Coke]> I think compiler release is too fine grained for that, but language release makes sense.
I see the bootstrapping issue you mention but what I propose is more or less the universal standard for documentation 15:42
Even if the docs haven’t changed since last point release, you still publish docs for the point release 15:45
Everything that came before is already being served by the current docs, so I don’t really see the issue there
Anyway, I will open a ticket to discuss, as you suggested earlier
[Coke] ab5tract: no, it's the same two things, but the clauses are in a different order. 15:59
wait. 16:00
re-re-reading. yes. language releases seem like a good scope for "per-release" docs. compiler release seems too much. Not because of the changs in docs, but I as a user also wouldn't expect to have to look at the docs per compiler version 16:01
also: what if we missed documenting something for, e.g. 2023.09 - depending on how we do the releaess, a simple tag isn't enough now to go back and fix the docs. 16:02
not *just* because of changes in the docs.
ab5tract the reason you as a user would select a specific compiler release of the docs is because that is the version you are using 16:20
The same way I look at Flink docs for 1.15 instead of “latest” or any other version
FWIW, this approach is so straightforward for auto generated docs that I can’t recall ever seeing it _not_ done this way 16:22
But we are in a different situation, I agree 16:23
coleman I'm not a fan of selecting versions from a dropdown. I think it's a bad UX and can be a maintenance burden. This is the argument I used when guiding some product teams away from it. 16:37
I think there are exceptions, such as...like... RHEL, where the release number is something you pay a million dollars for and talk on the phone with support about 16:38
However: 16:39
I wouldn't oppose this change but we are not set up for it. 16:40
ab5tract I think having a dropdown is more polite than what many auto-generated docs do, which is force you to edit a version sub-path in the URL (or find the magic index page that links between versions) :) 16:43
regarding setup, I hear you
coleman I think working towards it will have benefits, whatever the web UX looks like.
So here on the docs page, we say we don't want to embed docs in the compiler source 16:44
github.com/Raku/doc
I think that should remain the case, but we could explore some automation around updates from Rakudo-> docs 16:45
or from Roast->docs
Something that retains the open-ness of inviting multiple implementations, but takes advantage of what we have 16:46
The people we have, rather
ab5tract I would argue that the existence of "As of Rakudo 20XX.YY , this became that" and so forth all throughout the docs already breaks the contract as envisaged in that statement, but I do understand the sentiment 16:47
coleman That is part of my motivation with opening this issue github.com/Raku/doc-website/issues/359
My thinking is, if we can get our pod-parsing code to reliably target a sql schema, we will have a schema that OTHER things can target 16:48
ab5tract that SQLite idea sounds awesome
coleman So a CI job in Roast or Rakudo could ALSO spit out SQL INSERT statements, and we can load those in
So we don't have to bikeshed new pod syntax, or have a philosophical debate about where canonical documentation lives, or rather we can keep doing that, but also dump all our stuff into a common database :D 16:50
I think it would be a very Raku/timtoady thing to do: in addition to the static site, the docs site can serve a 10 meg sql file that anyone can download, and we let a 100 flowers bloom 16:57
But back to the original suggestion. I think a good prerequisite to serving versioned docs is proving that we have all that information as structured data in the first place. I'm not convinced we do... maybe we do. But loading a relational DB with a "version" table we can join to a "roles" table is a great way to test that. 16:59
That's a downside of ad hoc inline version info; you might not always be capturing it in an easily parsable way. Things can slip through. 17:00
[Coke] we don't even have it as unstructured data. 18:36
not entirely. there are some stabs at it as ab5tract noted with "prior to 2023.xx, this ..." 18:37
We should consider what we want the docs to look like when 6.e drops
Having the doc site polished for content for at least 6.d vs. 6.e would be nice.
23:59 sena_kun left

Powered by Cro and the Raku® Programming Language.

Please report any issues / comments / feature requests as an issue on App::Raku::Log.

Thank you!