Harmonize standard library overviews

[mamachanko]

Describe the problem/challenge you have

The ytt docs on its standard library appear differently in the sidebar than in detail. The former lists some that don't appear in the latter, while the latter aspirational groups by category.

I find that confusing. As a reader and user i find constantly second guessing myself as to whether i am missing something.

Describe the solution you'd like

It would be great if both would tell the same, consistent story. As a reader I would love to focus in the content without having to reconcile minor inconsistencies.

Anything else you would like to add:

Yes: ❤️ Carvel

[aaronshurley]

Nice catch, @mamachanko! Totally agree, this is confusing and could be improved. We're currently in the planning stage for some upcoming work so it's possible that we can get to this after the next release lands. If you'd like to give this a shot, PRs are welcome :)

cc @pivotaljohn for awareness

[pivotaljohn]

You are quite right, sir!

@mamachanko, I've been picking at the overall need to re-organize ytt's docs — in general — and one notion that popped up is to push down the module listing off the left nav entirely (and absorb "@ytt library" into the "Reference" section).

So, that thinking is just off-the-cuff and ad-hoc— so it's questionable. But if that turns out to be a good idea, then it would nullify any efforts to sync, here.

More durably, I suspect that we really want a singe page per module.... even if that means some pages are small.
This has been happening gradually ... you'll notice that some of the sections in the page you snapshotted are nothing more than a link to some other page...

Further... those individual pages vary in format:

• some are highly-structured: https://carvel.dev/ytt/docs/v0.42.0/lang-ref-ytt-overlay
• some are a terse summary and some examples: https://carvel.dev/ytt/docs/v0.42.0/lang-ref-ytt-assert/

... sooooo ....

For anyone interesting in digging into this, here's a suggestion for a starting point:

Part of what we could really use here is a bit of a well-informed direction for these reference pages...

• who uses to reference pages? what are they up to when they do?
• what's the best format for that information given those use cases?

and from there, we can start migrating these pages into a cohesive standard library reference.

[mamachanko]

For anyone interesting in digging into this, here's a suggestion for a starting point:

Part of what we could really use here is a bit of a well-informed direction for these reference pages...

• who uses to reference pages? what are they up to when they do?
• what's the best format for that information given those use cases?

and from there, we can start migrating these pages into a cohesive standard library reference.

As a user and aspiring contributor to ytt I shy away from the research part, but I think I provide myself as a data point.

When "using" the docs, I want to:

• understand what's available as built-in libraries
• understand how to use each built-in library's API
• be sure that what I see is all there is

Topical grouping, e.g. "serialization", is not very interesting to me.

[...] those individual pages vary in format:

some are highly-structured: https://carvel.dev/ytt/docs/v0.42.0/lang-ref-ytt-overlay
some are a terse summary and some examples: https://carvel.dev/ytt/docs/v0.42.0/lang-ref-ytt-assert/

I find the overlay's docs to be the gold standard here. They are complete reference, laced with realistic examples.