Module / Package documentation is structured suboptimally

[patrickbkr]

Currently we have:

• https://docs.raku.org/language/packages
• https://docs.raku.org/language/module-packages
• https://docs.raku.org/language/modules
• https://docs.raku.org/language/modules-extra

These pages are not interlinked consistently. The topic each page covers is not differentiated clearly from the topics of the other pages.

Latest case of confusion:

<pie_flavor> In the docs, the Packages page has lots to say about how to interpolate arbitrary variables into FQ names, but not how to turn FQ names into local names. Does Raku have any sort of import/use/using/alias construct, and if so, where should I have been looking for it in the docs?

[JJ]

That's not exactly the reference documentation, but tutorials, which are structured... let's say freely, if at all. So what you mention is not limited to that set of pages. Ditto could be said for regexes, for instance. But what you quote is a different thing, and I guess it could be addressed.

[wayland]

Hi!

We have 4 pages in the Language section on modules, one of which is quite large. I'd like to propose that we do a complete reorganisation of this. My overall plan is:

• Give modules their own subdirectory within Language
• Break them into more pages, and ensure that the names give a better idea of what they're for

Specifically, I'd like to see the following organisation:

• Modules: an Introduction
  • From:
    • Modules >> Basic Structure
    • Module-packages >> (What are modules?, When to use modules, Working with modules)
  • Add: links to the other Modules pages, below
• Using Modules: Finding and Installing:
  • From: Modules >> Looking for and installing modules
  • Add: a bit more guidance on raku.land
• Using Modules: In your code
  • From: Modules >> Loading and Basic Importing
• Using Modules: The Tools (a writeup on zef)
• Making Modules: The Tools
  • From:
    • Modules-extra
    • Modules-core
• Making Modules: The Code
  • From:
    • Module-packages >> (the rest)
    • Packages
• Making Modules: The Configuration and Structure
  • From: Modules >> Preparing the module
• Making Modules: Uploading
  • From: Modules >> Upload your module to CPAN/zef/p6c

We could also include fixes for:

• Mention App::Mi6 and the like in the modules section #4341
• zef should be in docs #4260

[coke]

Looks like a reasonable plan of attack.

[wayland]

Have made a PR at #4570 . Feel free to tell me to break it into smaller pieces or something.