About the documentation in general... > > that particular pair-input syntax is my least favorite. > > Flipping around the order of key and value when the value is a numeric...? > > > > And it isn't needed to demo the operator, any pair input syntax works. > > I might argue that examples should .... > > I think the docs reflect a desire to show rich examples that go > beyond the bare minimum. > > For some purposes that's a great thing. For others it's a bad thing.
Yes, precisely. I can understand wanting to have some flashy virtuoso raku code out there to show off the language, but I typically want to see at least a few very basic examples that don't rely too much on other knowledge (how much is too much is always a tricky one). > If you are willing to put a *great deal* of effort into helping evolve the > doc by both patiently discussing your concerns AND also *writing* > and/or *rewriting* doc in accord with a mandate to do so based on > a rough consensus, where rough doesn't mean unfriendly to any of > those involved, then I am 100% with you, and may even be talked > into helping a bit. No, no, when you want to talk someone into doing a lot of work you tell them how much *fun* it is. In general I like the material in the docs, but often I think the features need to be introduced with a few more simple examples early on (in the spirit of SYNOPSIS sections). I would think this kind of thing could just be done piecemeal without being a massive project. I guess if we were talking about a policy change to say, always have input data that looks like the .gist output, that might take some discussion, but even that isn't something that would have to be rolled out all at once. > Otherwise, I think that by far the most important thing is that we > support folk who both really care about improving the doc ... Sorry if it sounds like I'm griping a lot. My tone often comes off as pretty negative even when I don't intend it. > > favor the form that "say" is going to spit back to you. > > I agree with the sentiment of reducing cognitive load on readers. Yes, that's exactly it.
