Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki
Set by [Coke] on 23 May 2022.
00:04 Kaipii left 04:23 Kaipii joined 04:39 Kaipii left 08:34 sena_kun joined 09:09 Geth joined 10:30 sena_kun left 11:10 Kaiepi joined 11:13 sena_kun joined
Geth doc: 2802c2bfdf | rir++ (committed using GitHub Web editor) | doc/Type/Scalar.pod6
add link; lose my; change phrasing (#4121)
 12:58
doc: coke self-assigned Documentation error .raku vs. .flat github.com/Raku/doc/issues/4120
99cb2abb8a | Coke++ | doc/Type/Iterable.pod6

Closes #4120		 12:59
doc: coke self-assigned Modules reference unused irc channel github.com/Raku/doc/issues/4109
coke self-assigned Tagging, versioning and releases github.com/Raku/doc/issues/2690

Remove reference to outdated IRC channel
Closes #4109		 13:25
14:25 Kaiepi left 14:34 Kaiepi joined 15:03 Nemokosch joined
Nemokosch Damnit, I know it's not the docs site 15:03
but somebody should feel responsible for it 15:04
[Coke] Yes. 15:10
Nemokosch it's more like a "shoutout" because there aren't so good communication channels if issues are just simply ignored 15:11
Which happens way too often I feel
[Coke] ok, but -docs isn't the best place to get that feedback. You might happen to get a hit from someone with a shared interest, but #raku is a wider net with more people that might be interested. 15:12
This is definitely a potentially frustrating aspect of volunteer driven support, I get it
Nemokosch you have a point but this topic failed there as well at least once 15:14
[Coke] No doubt. 15:16
always possible that none of the current volunteers feel strongly about the topic *OR* even if they do, feel that they have the ability to address it.
Nemokosch I mean, ultimately nothing can solve the problem of no attention, except for attention
there is nothing that could force anyone pay attention
[Coke] Making it a positive suggestion for something to work on is probably the best thing you can do if you feel it's important but don't feel that you are the one to work on it.
Nemokosch I think the problem goes deeper than that. I have started dealing with several things, trying to push wherever I can. the Raku-ideas repo I uploaded is an artifact of that. 15:18
Mi6: pending PR for more than a month. Ddt: trying to clear things up with kalkin who abandoned Raku anyway. raku.org: pending on the lack of clear intents. docs.raku.org: something is going on but sena_kun is already burned out on infrastructure just not showing any progress 15:19
Richard's citation index: pending on lack of feedback from lizmat on the ecosystem module (retrieving data based on publish date) 15:20
Several broader language design and documentation issues, Rakudo bugreports 15:21
[Coke] the raku-docs burnout is a story in itself. Infra team is working on that now, but there's a technical snag they have to resolve.
My 2c summary: there's more work than we have volunteers, and everyone is probably suffering a bit of burnout. 15:22
Nemokosch Backend stuff: vrurg lowkey advertised a sort of crashcourse and went basically unavailable
(that's not an immediate blocker because on my end, I should watch the presentation from last year) 15:23
I'm really trying to "chase down" the people who are available in any way
[Coke] I have done this myself: "hey, I can do this thing where I see a gap". *2 weeks later* "oh no, I am also not in a great position to work on this." 15:24
Nemokosch hence sena_kun++ because out of that many people, he is almost the only one who at least _accepts_ work
[Coke] so, if everyone is already a little burned out, just be careful when "chasing down" so that it's not more pressure. 15:25
I think we have *one person* who is doing this as their full time (volunteer) job, everyone else is best effort.
Nemokosch Tbh I think it's a bigger problem that volunteer effort is not received. I can't say "not received well", it's not received *at all* 15:26
[Coke] and I admit that my best effort since JJ left has not been great (nor even my best)
Nemokosch There is nobody to actually take responsibility for connecting things.
[Coke] Sure. too much work, not enough volunteers.
Sure.
so how do you fix that?
Nemokosch Honestly? People who are kind of representatives of the Raku community, dedicate time and effort to *management* 15:27
I have concrete ideas about "management" if that's the problem
[Coke] working with existing volunteers can help. applying pressure to already stressed volunteers probably does not. (not saying you're doing that, just asking you be aware of this as you try to track down status of ongoing projects)
Managing a fully volunteer staff do3es
... does provide great challenges over managing employees/consultants. 15:28
Nemokosch The problem is, as you can see, that there isn't one single person to count on with this. Not one.
[Coke] Yes.
Nemokosch One could be enough, perhaps. But there isn't a single one
[Coke] Welcome to OSS software development without a corporate sponsor.
Nemokosch Also, you know, the more time I spend trying to build up a bigger picture and collect things to work on, I notice that there used to be people like that from time to time 15:29
It's easier to go back only a couple of years because Github 15:30
And yes, AlexDaniel was such a person. JJ Merelo was such a person.
[Coke] Sure, I've been involved with this project for about 20 years. We definitely had people like that, back through Parrot days.
and you'll note that many of those people get burnt out. 15:31
So, I agree with what I think is your point: having more people who can devote more time, esp. at an organizing level (as opposed to a reactionary one) would be great. 15:32
Nemokosch I don't know the "AlexDaniel incident", nor do I want to get deep into it. But it does make you think what can escalate about somebody of the very few people who dealt with management
I think, to hit a stricter but also clearer tone: if the Raku community has kind of an elected governing body (of volunteers, sure, but candidated volunteers who accepted the responsibility and are allowed to step back), it's their task of assuring minimal service to make sure processes don't pend on the lack of decisions and clear communication. 15:38
[Coke] That's the RSC, and you should take that up with them.
my recommendation: be constructive, volunteer your own time to help where appropriate. 15:40
sena_kun Nemokosch, I feel you on a very deep level.
[Coke] But that's definitely off topic for raku-doc.
Nemokosch++ sena_kun++ 15:41
afk for a few minutes.
sena_kun I agree it's a problem to keep things afloat unless you get paid for it (or anyone gets paid, as in corp-driven languages). 15:44
It can be countered with a large community, but we don't have that. 15:45
I have absolutely no fucking clue how does it work that some projects just take off and 99% don't. 15:47
Nemokosch of course that's a thing but this is a recurring feel of me that we don't lack *the people*. The people are still largely here, hanging around. finanalyst, jjmerelo, AlexDaniel, Util, p6steve, salortiz, and so on and so forth. Surely I wouldn't even know all the "relevant" names
We have more resources and content than we think (or pretend) we do 15:48
sena_kun Nemokosch, the people you mentioned are either not interested (JJ, AlexDaniel) or contribute when they are interested, which sometimes equals "once in a year".
it's not a sustainable day to day work 15:49
regarding the docs
Nemokosch I mean, JJ is a member of RSC to this very day, and still managing the advent calendar
so it can't be both at once 15:50
and even AlexDaniel didn't downright vanish, had commits this year as well here and there, maybe joined the conference as well, so I think it's accurate what I said 15:51
You might as well say I feel strongly about this sentiment and I'm not easy to be convinced. It's NOT the people that we miss the most, not even close. 15:52
It's the organisation, the management, the communication, you name it.
Not towards the outer world, towards each other 15:53
sena_kun I don't want to speak badly of anyone, but from my perspective the situation with the docs is extremely strange. When I introduced the website I was working for a year or something, and JJ was aware yada yada, Richard appeared and said "wait a minute, there is already MY website I developed for more years than you did". After some awkward conversations I thought "Ok, you don't like what I do, but you have your own project that
you claim is better. I don't care who wins, so just finish your project, deploy it, let the users get the improvements" and stopped working on that. And after a year what I saw is that.... Almost nothing happened! I don't know all private circumstances of him, but to me it's either you do or you don't interfere others who do. We lost more than a year, when the project was fresh and had more people interested, more traction etc,
cause of the "I won't do it, but I won't let you do it either" approach.
Nemokosch And this is the most ironic about the Raku community.
sena_kun s/was working/was working on/ 15:54
s/interfere/block/
Nemokosch Well I mean yes, that I would also consider part of the "failed communication" section 15:55
I think I came across that site just yesterday, by the way 15:56
sena_kun yes 15:57
did you like it?
[Coke] I am certainly part of the problem - tried to step in after jj left, but haven't had the cycles to contribute in a meaningful way. 15:58
Nemokosch to be honest, I don't remember and can't even find the hosted site itself right now xD 16:01
perhaps I should have paid more attention at the conference... tbh those were really long days and I was excited and got tired 16:02
sena_kun Nemokosch, I feel your frustration, anyway. I think the question all of us should send is does the work itself gives more than it takes. 16:03
Nemokosch so basically what I paid the least attention to was the stuff about documentation :-X
sena_kun the language market is a pie already cut and eaten, the changes of something to become popular at this rate are extremely slim 16:04
it's not an existential issue in itself, I mean, dozens of languages live this way
Nemokosch what frustrates me is really this thing that the community is surprisingly... individualistic or how to put it 16:05
self-fulfillment, self-fulfillment... not saying I'm that different with things that I feel strongly about, but those are usually language things that get frozen rather soon 16:07
for the docs - I'll help with whatever seems useful, being decisive is more important than the decisions themselves 16:08
sena_kun Nemokosch, if I understand correctly, a lot of people who were the core in say 2005-2015 sort of "grew up" (not in a kid->adult sense, but they are not students anymore who can hack days along, now they have suits, kids, $dayjob to $paycheck), those people who were talking to each other on conferences and on irc
who left are either dealing with the same kind of problems or not interested enough to pay attention on a daily basis 16:09
that's the impression I have
[Coke] so, bringing it back to docs - we could definitely use an editor. We could use someone willing to go through the checklist tickets and writing docs for missing items. (more of these if you run whatever the xt/ test is that compares docs against rakudo source)
If actually writing docs isn't your thing, tell me what is your thing, and we'll see if we can make use. 16:10
Our biggest project is "finally get sena_kun's new site deployed" 16:11
Nemokosch Another related idea is: if we really let go of the so-called "old design docs" (which, according to niner, were basically left behind simply because of the lack of interest/effort) - we could, once and for all, read them and incorporate them into the docs, whenever the behavior is still in accordance with Roast 16:12
[Coke] I don't think that is helpful; design docs are definitely historic at this point; not everything made it into the language; and the raku docs site, while it has some "why is this this way", should be more "this is what is" 16:13
Nemokosch An example: I opened a monster issue on the Problem solving repo about the semantics and current behavior of hyper metaoperators. It's much better described in the "old design docs" than anywhere else
[Coke] ... That said, if someone did that work (dredged the historic docs for content for the new site), I would hardly refuse new content; but comparing against Roast would be a better targetr, IMO 16:14
Nemokosch The problem is that Roast is both lacking and not very readable in general
[Coke] so for that one case, updating the docs may make sense using design as a starting point. Would be happy for a PR that did that.
yes, but it's up to date. 16:15
You wouldn't be able to lift and shift the docs, but you could verify the topics were covered.
Nemokosch That needs to be done either way tbh :D
[Coke] it would be *easier* to get text from the design docs, but more likely to be out of date, require review.
But there's so much stuff already id'd in the bug log, that if someone is looking for particular items that we know need docs... we have a great starting point there. 16:16
Please as you think of potential docs work, throw it in a gist or a wiki page somewhere so we can respond or add it the queue. 16:17
Nemokosch That's why I brought up this example. I spent several hours writing an issue about the poorly documented details of hyper meta-operators (no feedback ever since, who am I kidding...) and it turns out most of that stuff was present and fitting in the "old design docs" 16:18
It was really a moment of "I wish I knew this earlier"
[Coke] that the design docs existed, or that this particular item was discussed in them? 16:19
You could definitely take as an item: review the design docs for items that appear to have coverage for items missing in the docs repo, and then you (or someone) would have to verify which of those are up to date, and get that content in the doc repo. 16:20
as someone trying to focus effort, if I get someone willing to write docs, I'll point them at github.com/raku/doc/issues?q=is%3A...bel%3Adocs to start (and we can prioritize those); if there are specific items from the design repo we can consider, great, but "go through all the design docs" is probably not going to be on anyone's list until we get more caught up, unfortunately. 16:24
closed #4064 16:28
here's a topic: do we want to have a single product for Raku docs (my preference) or one per language release? 16:36
sena_kun [Coke], can you please elaborate? 16:37
[Coke] I am HEAVILY in favor of the former (all basically to minimize volunteer time), but if anyone has a strong argument for the latter, let me know.
if a method is in 6.d but not 6.c; should there be a single set of docs that shows the method and says it was added at some point, or *two* sets of docs, one that includes it and one that doesn't. 16:38
in java docs, for example, it's tied to release, so go to "java 8" and look stuff up there, not to java, then a class, then find out it doesn't exist until 8.
(our release model and current infra and staffing level isn't really suited to separate documentation products, IMO) 16:39
we are also complicated in that we can also report out when things were added to the implementation, not just the language. Or the backend.
we already would have to say "NYI in JVM", e.g. "added in v6.e" seems to be equivalent. 16:40
github.com/Raku/doc/issues/2690 16:41
... which starts off on that point but then veers off into a discussion that I'm not 100% following. 16:42
also, if we had releases of docs, we'd basically lock in old docs; any updates would either only go into the newer version (or we'd have to release updated docs for old releases) 16:43
16:45 Kaiepi left 16:46 Geth left, Geth joined 16:47 Nemokosch left, Nemokosch joined
Nemokosch same feelings
what makes the content and the presentation so tied?
[Coke] ok, closed 3 tickets today, that's something.
there is content, it's transformed for the web site. some of that tooling has been extracted. with sena_kun's website, we can do a better separation (his site isn't *required* to succeed at the separation, but he's already done it.) 16:50
Nemokosch so that part of the issue might turn outdated? 16:54
sena_kun [Coke], it's an interesting question. 16:55
I brought it up many times, but I have no preferences / opinions. My idea was to start trying with heavy things like versioning once we have the website and then the website turned out to be a stalker release. 16:57
Nemokosch stalker release? 17:05
sena_kun erm, something that takes longer than expected, an event that gets postponed many times 17:08
Nemokosch lmao 17:15
sena_kun the idiom is not about the new game by the way, but about the first in the series 17:25
17:50 Kaiepi joined 19:32 sena_kun left 20:10 sena_kun joined 20:34 sena_kun left 20:35 sena_kun joined 21:44 Nemokosch left 22:25 sena_kun left 22:26 sena_kun joined 22:38 Nemokosch joined
Nemokosch Back to the docs site and the autocomplete... 22:47
I checked two prewritten libraries that weren't quite frameworks, only for this particular task 22:49
codepen.io/trevoreyre/pen/JjGxLEm
based on github.com/trevoreyre/autocomplete 22:50
pro: small, seems very simple vanilla JS, not a huge risk or load 22:52
con: doesn't seem too maintained; still needs some handwritten adaptation 22:54
the other thing was jsuites.net/v4/dropdown-and-autocomplete 22:55
Pro: built-in support for grouping and the default behavior seems sooo much cooler than jQuery Autocomplete was... 22:56
Oh and also it seems pretty well maintained 22:57
Con: in some sense, it is like jQuery: you can't just pull the relevant part, and perhaps it has some opinionated things (like own CSS sheet) 23:00
I'd say the standalone autocomplete lib is the safer choice while the jSuites plugin is the more elegant choice 23:03
Neither of them would require massive redesign outside of the search itself
23:16 Kaiepi left 23:24 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!