search

carvel-dev / carvel

Carvel provides a set of reliable, single-purpose, composable tools that aid in your application building, configuration, and deployment to Kubernetes. This repo contains information regarding the Carvel open-source community.
https://carvel.dev/
Apache License 2.0
374 stars 111 forks source link

Harmonize standard library overviews #551

Open mamachanko opened 2 years ago

mamachanko commented 2 years ago

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.

image

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 commented 2 years ago

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 commented 2 years ago

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:

... 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...

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

mamachanko commented 1 year ago

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:

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.