ordering of documentation is sometimes suboptimal

[karenetheridge]

toolchain:

11:52 @haarg CPAN-Meta is one of the dists that shows the unfortunate way metacpan list docs sometimes 11:53 @haarg the historic meta documents all are given priority over the current stuff 11:53 @ether yeah :( 11:53 @ether the first section should be all .pod, and modules with docs, all together, followed by modules with no docs. 11:54 @leont I can hear a new meta field coming :-p 11:54 @ether x_documentation_order ? 11:54 @ether could be useful to ensure that a certain doc is on top 11:54 @ether e.g. in the Moose dist, I'd want to put Moose::Manual on the top 11:55 @ether and Moose::Intro

[oalders]

I can see how there might be a lot of different opinions on how to order the docs. If there were a meta_field for this, we could use Sort::ByExample to use any custom sort order. I'll close this issue for now as I don't think it's actionable without a new key. We can re-open if/when we get to that point.

[karenetheridge]

Do we just need someone to ship a distribution inventing an x_ meta key that contains this information? If so, I'll happily do so with Moose. I'll raise this at the QAH discussion on meta spec revisions.

[karenetheridge]

or perhaps we can use @ribasushi's Acme-WeirdPod distribution?

[oalders]

Sure, that sounds good to me. Just let me know when there a testable dist and we can re-open this issue.

[karenetheridge]

It's time to re-open this ticket! :dancing_men: 💃 👯 💃 😃 🍰 :dancing_men:

As of version 2.2000, the Moose distribution now has a x_documentation metadata which lists the modules which should be placed at the top of the 'Documentation' list.

[karenetheridge]

I'm looking at this again and wondering how we would use x_documentation (as I trialled it out in Moose) for CPAN-Meta, where we want to put certain documents at the bottom of the list rather than at the top...

Should x_documentation simply list the desired order of all documentation modules (and those not listed should follow after)? therefore, for CPAN-Meta we'd see metadata like:

x_documentation => [
    'CPAN::Meta',
    'CPAN::Meta::Converter',
    'CPAN::Meta::Feature',
    'CPAN::Meta::History',
    'CPAN::Meta::Merge',
    'CPAN::Meta::Prereqs',
    'CPAN::Meta::Spec',
    'CPAN::Meta::Validator',
    'Parse::CPAN::Meta',
    'CPAN::Meta::History::Meta_1_0',
    'CPAN::Meta::History::Meta_1_1',
    'CPAN::Meta::History::Meta_1_2',
    'CPAN::Meta::History::Meta_1_3',
    'CPAN::Meta::History::Meta_1_4',
]

Would this not be ambiguous given that some of these modules are in fact listed in the 'Modules' section on metacpan, rather than in the 'Documentation' section? I suspect more bikeshedding is needed on the format of this metadata.

cc @haarg

[haarg]

It might make more sense for this to be a list of files rather than a list of modules.

[rjbs]

I come to this ticket by way of fretting about the perl distribution.

The "ordered list of files" approach looks good to me, although I think I might like one more layer of organization, like:

{
  "sections": [
    { "name": "Overview", "file": [ "...", ... ] },
   ...
}

…to replace the existing "Documentation", "Modules" and "Examples" &c.