Rakudoc in third-party modules and some related topics

This is a meta-issue as it is about to cover a few topics I stumbled upon while writing docs for my last module. Perhaps it would make sense to spawn more specialized issues later, but for now it feels to me like having more sense in providing general overview of the situation.

It is also to be noted that I've got an answer to at least one of my question, but it was part of an undocumented conversation. Therefore it'd be included here as well. Other answers could be lurking out there too, but they're not known to me.

I would try to structure this from the perspective of a module developer, possibly not very experienced with documenting in Raku.

Where To Start?

Turns out we don't have a manual on how to write manuals. Something I'd rather expect to be part of module development section in the Raku documentation, or be linked to from the section. What I would like to see there is:

Where to start in general, including such topics as recommended sections and styling in general
How to organize the docs from distribution perspective: file locations, pros and cons of using dedicated .rakudoc, or inlining into .rakumod, etc.
What tools to use.

I'd say this all is better be a single piece since, as a rule, writing docs is the final stage of project development.

Docs In An Installed Distribution

Giving further development to the item 2 from from above, there are cases when having documentation inlined into a .rakumod is not considered a good idea. My own latest example is LibXML::Class::Manual which is not a module and better not be. Other cases may include documenting classes which are declared within a module but one wants them to be available for a documentation reading tool by their full names:

unit module Foo;

class Bar {...}

And then:

$ rakudoc Foo::Bar

Our current Raku documentation states that .rakudoc are to be placed under doc/ directory of distribution source tree. But the directory is never included into precompiled installation. Thus, zef install Foo and then wiping zef's cache would leave one with no access to these docs whatsoever.

Though, for the clarity, even having the cache preserved is of little help because one has to know where is it located before using it. Moreover, if they don't know about the cache existence then it's not much different from not having it in first place.

The Reading Tool

For those coming from Perl background, having rakudoc is quite natural expectation. To be frank, I don't know what is the situation with documentation readers in other languages, but having one should be considered an advantage. From this point of view I tend to consider having the rakudoc as the standard.

Either way, there is no alternative to it presently. But in its current form it is barely useful too.

First of all, it requires a document to follow its demands with regard to the structure and it is very rigid in these demands. In particular, it has to be =TITLE, not =head TITLE, not =head1 TITLE. But then again, why =TITLE and =SUBTITLE, after all? My own preference is man-styled docs with =NAME, =SYNOPSIS, =DESCRIPTION, etc. In large due to keeping in mind that this how they should be used too.

The other requirement is to have :kind, :subkind, and :category keys on =begin pod – but what are they? What for? Seems like this is something apparent to The Raku Documentation project participants, but they are an undocumented mystery to me.

It is understandable that since rakudoc is not part of Rakudo and, apparently and definitely, of the Raku language, I cannot impose any requirements on it. But without an alternative implementing more democratic rules I'd have these question open. It is irrelevant to me wether they'd be answered by rakudoc or somebody picks up the task and implements a "competitor".

And then, once again, access to .rakudoc in precompiled distros...

Tooling?

Having some kind of standard tool or tools to deal with documentation, starting from verifying it and all the way down to producing output formats and even publishing them – it's a dream. Let it be here, just in case...

BTW, with RakuAST implementing this part would become more feasible.

TOC?

I'm not even certain as to what to ask about here. Some documents (the above mentioned manual, in particular) tend to grow big. Having TOC would help a lot in navigating them. Even if it's not clickable since having a document overview already eases search for necessary information.

Some docs are so tiny that TOC in them would be an overkill.

Having TOC as a part of Rakudoc standard seems to be an advantage. Making it available for opt-in/opt-out would be great too.

Rakudoc Cross-linking

L<> tag is giving more questions than answers. The first and the biggest problem is when it comes down to multi-format output (HTML, Markdown, etc.) where there could not only be different file extensions but even different directory structure – if there is any directories at all like when everything is thrown into a single PDF, for example. There is a real-life case of https://raku.land where links in READMEs are very fragile and often just do not work.

What aspects of linking we can take as axioms?

anchors (explicit or implicit)
inter-document
cross-document
the already mentioned multi-format output with different file extensions and URI schemas

A typical question of linking would look like: in a doc for module Foo::Bar::Baz I need to link to a paragraph in Foo::Fubar documentation so, that it would work in a local HTML; on a web page; on a version control service provider like GitHub, GitLab, whatever else is one's choice; etc.

Perhaps this question doesn't have a comprehensive answer, but at the moment there is barely anything reliable but WWW URLs. Not even relative paths are sufficiently good for the task.

Raku / problem-solving