Improve ability to find cloud docs

[joeduffy]

After coming back from vacation, my mind was fresh, and I honestly had a hard time finding our cloud docs, and really don't find our organization of content intuitive. I simply wanted to link to "the Kubernetes page" for a customer asking about it.

If I go to our "docs" (probably where most people would go), I see Kubernetes on the upper left:

Alas, clicking that does not take me where I wanted to go. In fact, even if I click the "Kubernetes" part of that link, I end up on a page that presumably should offer to link me to the docs in case that's what I wanted. Instead, it discusses Minikube and NGINX.

At no point in navigating to the docs did it offer "the registry" as an option. In fact, is the registry -- arguably the location for the most important content on our site -- not even in the top nav, or am I dreaming? I see it tucked away in the upper right alongside other less important linkage like our GitHub star count, Slack channel, and sign in button, but that seems to do it a disservice.

At this point, I "knew" as a Pulumi employee that clicking "registry" was where I wanted to go (although, to be honest, when I'm trying to figure out "how do I use Pulumi with AWS (or Kubernetes (or ...))", I'm not sure I'd immediately think to go to the registry. And why is "registry" a different option than "docs" anyway? It would seem to be a subset, not a peer, concept?

Eventually, I found the "Cloud Providers" link on the left -- beneath Architecture & Concepts and Pulumi Service -- again, buried amongst other things (and even sorted beneath them) that probably aren't nearly as important as a Pulumi end user.

I click that and, confusingly, the left nav entirely disappears!! Ugh! But then I am just one click away from where I wanted to be.

Again, I may have missed something obvious, but it was a slightly frustrating experience. I still find myself longing for https://github.com/pulumi/pulumi-hugo/issues/947.

[susanev]

i fully agree that our docs navigation is not centered on our users, is confusing, and absolutely causes folks difficulty in finding docs that we have.

a few additional points...

• I do not think the parent of Intro makes sense for the content that is contained within it. i previously have proposed that we make arch+concepts, pulumi service, and languages top-level items. and then introduce a new category that contains the compare to, adopting, and converters content.
• the names of the items under get stated are confusing, i previously proposed using longer names to describe what they actually are

lastly, moving all registry content to totally different place has an impact on the usability of finding things. do these really need to remain separate? if we cant combine them, we could have a parent item of registry in the left nav of docs, but i really don't think that will solve this problem completely.

[joeduffy]

Agree with most of that. The thing I always had in mind was something sort of like this:

If you couple that with your ideas to make some of those top-level nav items, and I think it'd be a major improvement.

[cnunciato]

I'll just drop another mention of the Diataxis framework here as well 😇, as it'll surely help light the way for y'all as you think about making structural changes like these -- discussion doc here:

https://docs.google.com/document/d/180KNNq8alShdOh-D-1QlysaINLoma94FagRgitpt1NQ/edit#

I think if we keep to that core principle of four types of docs -- tutorials, how-to guides, explanation, reference -- and keep organizing around that, we'll be good. See the doc for a mapping of how our content today fits into each of those four categories.

In this case, what you wanted was "reference", but the link dropped you into "tutorials" and then didn't give you a clear path to finding what you were looking for. I thought we had an issue suggesting we link from the get-started landing page for each cloud to the package docs in the registry for that cloud (though I'm not finding it now -- maybe it was mentioned in passing), but IMO, that'd just paper over the problem of people landing on these pages erroneously to begin with. We could link to the Kubernetes docs from /get-started/kubernetes for example, but ideally, folks looking for Kubernetes docs just wouldn't end up on this page at all. I actually wonder whether a good chunk of the confusion here would've been avoided by just not having those links listed underneath Get Started, given how prominent they are. People definitely do click those links -- but what isn't clear is whether they're actually looking to "get started" or just looking for docs on that particular cloud. My hunch would be it's the latter, given your experience and how often they get clicked from /docs and /get-started, but it'd take a bit more digging in GA to confirm that.

We've also heard much of this same this feedback before, especially around the problem of package docs not living under "Docs". Once people figure out that these docs live under Registry, they seem to like having everything together like it is now, but that hard separation between Registry and "Docs" definitely leads to a good bit of confusion.