Re: Module Documentation
So here's my 2¢, which will probably be followed up with some actual development of stuff (I do put my money where my mouth is… although it might take me a while to save up to spend it ha). Some of the minor details could, of course, easily be adjusted, so don't fixate too much on them. Right now, it is true that many of us use README.md for github. Some people write this one by hand (I'm guilty of it), others (lizmat, for instance) generate this from their *.rakumod file. We can do a lot more with POD6 than we can with MD (as POD6 encodes things more semantically than MD), so we should encourage pushing towards using that, and then using a script to generate the MD (or HTML, in the case of a website). The following would be my rough proposal: (1) Standard the function/meaning of reserved blocks (e.g. =TITLE vs =NAME, when to use one or the other or how they should be different). Perhaps as larger projects like Red or Intl document extensive/larger documents, we can see what patterns might emerge and evaluate. (2) Just as we have /t, /lib, and /bin as standard module folders, use /doc[s] as a default space for documentation. For those that prefer not to use inline documentation, their pod6 files would reside here (which could also be identically-named rakumod files, esp. when wanting to have declarator pod included). In any case, .md files could be autogenerated here for use on github, or .html for elsewhere. README.md (or index.html, for webpages) could be autogenerated for github based on 4b. (3) Localized documentation in /docs/local/zzz-XX. The localized documentation could be made from a skeleton/fully stubbed file rakumod file (for declarator stuff) or from a standard pod6 file whose file names coincide with the docs (or lib) versions. I'd be happy to do some of the work here, as I plan to localize a fair bit of my documentation for certain modules. (4) To help with the above, several new META6.json keys: a. docs-lang for the language of inline documentation (en default). b. docs-root for the module whose docs will serve as a front page (e.g. README.md or as the first text on aggregator pages) c. docs-ext for an outside link to documentation, which would be a fallback to any other documentation and contrasted with a general website. For 4c, these could be added to the support entry, as support->docs and support->website, and the docs-lang/docs-root could be under a single entry with two subkeys. Anyways, lengthy 2¢ but there we go :-) Matéu > On Mar 2, 2021, at 08:25, Richard Hainsworth wrote: > > Hi, I want to create a system that will show documentation about Raku Modules > that I have installed. > > There does not seem to be a Documentation standard, or best practice, for > Raku modules. > > Hence the following post. > > In the Modules documentation in the Language section of the Raku > documentation, there is a single mention of README.md, but only that it is > needed by github. There is no indication about what should be in README.md > > As a user of Raku, this does not matter much to me in practice, as when I > need to understand something, I look at the code on the repository. But it > can be a hassle going to Modules.raku.org, finding the module, going to the > repo, finding where the information is, etc. I do NOT try and find the > information that has been installed by zef because the location names are not > human friendly. I understand the reasoning there, and do not suggest any > change. But it is not easy to find documentation on locally installed > modules, even though the information is there. > > Even the "zef --open browse source" command opens a browser to the > internet repo, not to the local installation. There is no "zef documentation > entity" or "zef README entity" command. I am NOT complaining about zef > because the problem is not with zef, per se, but with the absence of a > documentation standard (I think). > > I wanted to incorporate a page with documentation of modules in the > Collection-Raku-Documentation system I have just released. > > But I do not see how to do this. > > Most Raku modules have a README.md, which is required because of github > requirements. Although the README's of some modules leave a great deal to be > desired. > > Many modules have extensive POD6 inside the main 'lib/module.pm6' file (where > 'module' obviously is a placeholder for this email). > > There is an issue on the GTK::Simple repo, which I am now the maintainer of, > for more documentation. Actually, I learnt how to use GTK::Simple by looking > at the examples in the repo, which have lots of explanation. But the > README.md is appalling. However, an unanswered question is where would I put > a documentation file when I write it, so that it is useful for users wanting > to understand more. > > In the modules I am now developing, I have a README.pod6 file, which I > convert to the README.md file
Re: Please create a Raku community channel
Hello Richard (and all), The simplest solution seems to be reviving the historical mailing-lists pertaining to the Perl6 effort, in particular, the "perl6-announce" mailing list at perl6-annou...@perl.org . Daniel Sockwell wrote as much in his recent email. New subscribers can sign up at perl6-announce-subscr...@perl.org . According to https://raku.org/archive/lists/ , "perl6-announce [is a] Moderated list for news of new lists, working groups, and so on. Summaries from the top-level working groups are also posted here." Presumably that includes reports from the Raku Steering Council. Yes, it can/should be renamed "raku-announce", but in the meantime why not use it? Best Regards, Bill. W. Michels, Ph.D. On Mon, Mar 15, 2021 at 4:19 AM Richard Hainsworth wrote: > > Thanks to everyone that responded. > > It seems to me that the establishment of a common communication channel > by the RSC (Raku Steering Council) would in itself define the Raku > Community. Those who want to be a part of the community would track > (follow, read, contribute etc) the channel. I don't think it is > something that needs to be over-thought. Every channel has its > advantages and disadvantages, and there's going to be someone who does > not like the result. > > But the current situation of multiple channels of communicating is > obviously going to create confusion. It would be like having multiple > places for defining the same set of constants for a software project, or > some other analogy of duplicating code that should be kept in one place > and referred to, not written and maintained in multiple places. > > Also, if like-minded people have a way to share and cooperate, a > community will build. Facilitating the growth of a community will have > an impact on the acceptance of Raku as a language. > > Having multiple differing approaches to the same problem can be good - > not arguing with that. But if there's no common way to share information > about the multiple approaches, how can the different approaches be > compared? If they can't be compared, then the advantages of multiple > approaches are lost. And no one can be certain that their efforts are > being considered. > > It turns out - from comments of JJ and Vadim - that Altai-man's > initiative is a personal one. Had it not been late at night (for me) and > had there been an established channel where plans for community > resources are shared, I would have realised that straight-away. Instead, > I got annoyed and lost sleep (silly and unreasonable, but I am human). > > Daniel, I look forward to hearing from you. Altai-man, please send me a > link that I can catch up with what you are planning (I'm not so good at > tracking multiple github repos). > > One of the things I would like to do is to set up a way of doing > documentation that will allow for multiple languages to be possible, > which means that it should be possible to show the same documentation > file side-by-side in two languages, with text for each language kept in > a separate file, but for equivalent places in the documentation to be > synchronised. It would also be good to have revisionning history > visible, so that updates in the main text can be tracked so as to update > in a target language text. > > Regards, > > Richard > > On 14/03/2021 21:16, Daniel Sockwell wrote: > > I agree with the points Vadim and JJ made: There's a good chance that > > having a more official > > communication channel would _not_ have prevented surprise here, since the > > amount of progress > > on the a potential docs redesign seems to have taken many people (including > > me!) by surprise. > > I guess that's what happens when our community has "forgiveness >> > > permission" as a core value! > > > > That said, I also agree with Vadim that we should have a better way to > > communicate things like > > this, > > even if it wouldn't have been relevant in this particular case. In fact, we > > theoretically do: our > > website lists the perl6-announce list, which is supposed to be "low traffic > > (a few emails a > > month)". > > https://raku.org/community > > > > Looking at the archive for that list, it has been **very** low traffic > > indeed: the last message was > > > > sent in 2015. So we clearly haven't been using it, and starting now (when > > we're about to finally > > move on to raku-* mailing lists) probably doesn't make much sense. But, > > once we do, making an > > effort > > to actually use the raku-announce list seems like a good way to address > > this issue. > > > > Finally, Richard, in the interest of not taking you by surprise again on > > the same topic, I wanted to > > mention that, inspired by the proposed doc site redesign and your comments > > about the broader topic, > > I'm now working on a proof of concept along the same lines (because I have > > a slightly different vision > > of what a redesigned website might look like, but don't think I can > > communicate it without a POC). I
Re: Please create a Raku community channel
Thanks to everyone that responded. It seems to me that the establishment of a common communication channel by the RSC (Raku Steering Council) would in itself define the Raku Community. Those who want to be a part of the community would track (follow, read, contribute etc) the channel. I don't think it is something that needs to be over-thought. Every channel has its advantages and disadvantages, and there's going to be someone who does not like the result. But the current situation of multiple channels of communicating is obviously going to create confusion. It would be like having multiple places for defining the same set of constants for a software project, or some other analogy of duplicating code that should be kept in one place and referred to, not written and maintained in multiple places. Also, if like-minded people have a way to share and cooperate, a community will build. Facilitating the growth of a community will have an impact on the acceptance of Raku as a language. Having multiple differing approaches to the same problem can be good - not arguing with that. But if there's no common way to share information about the multiple approaches, how can the different approaches be compared? If they can't be compared, then the advantages of multiple approaches are lost. And no one can be certain that their efforts are being considered. It turns out - from comments of JJ and Vadim - that Altai-man's initiative is a personal one. Had it not been late at night (for me) and had there been an established channel where plans for community resources are shared, I would have realised that straight-away. Instead, I got annoyed and lost sleep (silly and unreasonable, but I am human). Daniel, I look forward to hearing from you. Altai-man, please send me a link that I can catch up with what you are planning (I'm not so good at tracking multiple github repos). One of the things I would like to do is to set up a way of doing documentation that will allow for multiple languages to be possible, which means that it should be possible to show the same documentation file side-by-side in two languages, with text for each language kept in a separate file, but for equivalent places in the documentation to be synchronised. It would also be good to have revisionning history visible, so that updates in the main text can be tracked so as to update in a target language text. Regards, Richard On 14/03/2021 21:16, Daniel Sockwell wrote: I agree with the points Vadim and JJ made: There's a good chance that having a more official communication channel would _not_ have prevented surprise here, since the amount of progress on the a potential docs redesign seems to have taken many people (including me!) by surprise. I guess that's what happens when our community has "forgiveness >> permission" as a core value! That said, I also agree with Vadim that we should have a better way to communicate things like this, even if it wouldn't have been relevant in this particular case. In fact, we theoretically do: our website lists the perl6-announce list, which is supposed to be "low traffic (a few emails a month)". https://raku.org/community Looking at the archive for that list, it has been **very** low traffic indeed: the last message was sent in 2015. So we clearly haven't been using it, and starting now (when we're about to finally move on to raku-* mailing lists) probably doesn't make much sense. But, once we do, making an effort to actually use the raku-announce list seems like a good way to address this issue. Finally, Richard, in the interest of not taking you by surprise again on the same topic, I wanted to mention that, inspired by the proposed doc site redesign and your comments about the broader topic, I'm now working on a proof of concept along the same lines (because I have a slightly different vision of what a redesigned website might look like, but don't think I can communicate it without a POC). I hope to be able to share more details in the coming days. Best, Daniel / codesections
