4 ms·

When I was looking at the language, I didn't find the documentation "really poor". In fact I was impressed at how much of a one-stop-shop the official docs site

When I was looking at the language, I didn't find the documentation "really poor". In fact I was impressed at how much of a one-stop-shop the official docs site was for both conceptual docs and API docs. https://docs.raku.org/ https://docs.raku.org/ Look at the following page as a jumping off point for conceptual stuff. Absolutely top class: https://docs.raku.org/language https://docs.raku.org/language

legends2k 3y ago
That's due to the Perl culture. Their FAQs and man pages were top class due to the kind of programmers who write Perl; funny, pithy and quirky.
layer8 3y ago
The Perl man pages were always excellent.
- fuzztester 3y ago
  Yes. I remember downloading them, as multiple PDF files, one for each broad subsection (like perlsub, perlvar, etc.) under the main TOC or so, over a somewhat slow Internet cafe connection and then reading many of them. Not only excellent content, but excellent typography and design too, even though they were mainly text. I remember, even now, thinking that the PDFs looked really good.
fuzztester 3y ago
>Look at the following page as a jumping off point for conceptual stuff. Absolutely top class: >https://docs.raku.org/language https://docs.raku.org/language Thanks for that.
landyacht 3y ago
As someone who has been doing Raku for several years now, I will say the documentation is both great and also lacking. Most of what's there is well written and includes useful example code, but I occasionally run across things that either haven't been documented at all or have only been documented for simple cases. The worst offender in my experience is the module system. There are docs around it, but they would benefit from a rewrite with a less "technical" audience in mind. The module/package distinction is difficult to wrap your head around just from reading the Modules page. The fact that the declared namespace of what you import can be different from the namespace you used to import, but the directory structure has to match the namespace for the compiler to find it... it's useful and makes sense in a strange way, but I had to learn that by fiddling around. # in Name/Space/Thing.rakumod unit class Thing { … } # in UseCode.rakumod use Name::Space::Thing; my Thing $thing .= new: …;

legends2k 3y ago

That's due to the Perl culture. Their FAQs and man pages were top class due to the kind of programmers who write Perl; funny, pithy and quirky.

layer8 3y ago

The Perl man pages were always excellent.

fuzztester 3y ago
Yes. I remember downloading them, as multiple PDF files, one for each broad subsection (like perlsub, perlvar, etc.) under the main TOC or so, over a somewhat slow Internet cafe connection and then reading many of them. Not only excellent content, but excellent typography and design too, even though they were mainly text. I remember, even now, thinking that the PDFs looked really good.

fuzztester 3y ago

>Look at the following page as a jumping off point for conceptual stuff. Absolutely top class: >https://docs.raku.org/language https://docs.raku.org/language Thanks for that.

landyacht 3y ago

As someone who has been doing Raku for several years now, I will say the documentation is both great and also lacking. Most of what's there is well written and includes useful example code, but I occasionally run across things that either haven't been documented at all or have only been documented for simple cases. The worst offender in my experience is the module system. There are docs around it, but they would benefit from a rewrite with a less "technical" audience in mind. The module/package distinction is difficult to wrap your head around just from reading the Modules page. The fact that the declared namespace of what you import can be different from the namespace you used to import, but the directory structure has to match the namespace for the compiler to find it... it's useful and makes sense in a strange way, but I had to learn that by fiddling around. # in Name/Space/Thing.rakumod unit class Thing { … } # in UseCode.rakumod use Name::Space::Thing; my Thing $thing .= new: …;