Module Documentation

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 <entity> 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 for github using a GUI tool in 
Raku::Extraction. The advantage of this is that the README.pod6 can have 
links to other pod6 files.

My suggestion is that some formal decision is made about documentation 
for Raku modules, that some documentation good practices are put 
together and included in the Modules page. My suggestion is that 
documentation should be in one of the following:

- the main module, defined (perhaps) as the pm6 file with the same name 
as the Distribution name

- a README.pod6 in the root

- a POD6 file pointed to by META6.json, eg a META6.json key that looks 
like: "documentation": "/lib/MyModule.pm6" or something.

• Module Documentation by Richard Hainsworth
• Re: Module Documentation by Matthew Stuckwisch
• Re: Module Documentation by Elizabeth Mattijsen
• Re: Module Documentation by Tom Browder
• Re: Module Documentation by Daniel Sockwell
• Re: Module Documentation by Tom Browder
• Re: Module Documentation by Curt Tilmes