It’s been a few months, but I’d like to reiterate @millions-furniture-75402’s pain. I have been a Pulumi user for several years now, and in the beginning, I found the Pulumi docs to be amazingly simple and helpful. There was a very simple set of “concepts” and all of the API docs were excellent reference materials.
For 99%+ of my Pulumi docs visits, the only page I really want to get to is this page: https://www.pulumi.com/docs/reference/pkg/ , but it’s always so hard to find.
I appreciate that those APIs have been put all onto one page, but the link to it is buried “beneath the fold” and has to be scouted out in the bottom left corner of the Docs page.
I don’t know the right terminology for this, but it seems to me that there’s a big difference between what I think of as “Docs” and what I think of as “Guides”. Currently, the Pulumi “Docs” section heavily favors “Guides,” but those become much less useful after you already know how to use Pulumi. It feels a bit like going through an onboarding flow every time I’m trying to find the API reference docs.
Of course, I don’t have the context that you surely do about usage, but from my perspective, it would be very helpful to have the link to the “Reference” and/or “API Reference” sections be treated differently than all of the guides. A couple of suggestions might be:
• Make “Docs” dropdown in the header that has “Guides” and “Reference” called out separately
• Or maybe add a “Reference” button next to the “Get Started” button on the Documentation homepage for people who aren’t looking for the full flow.
• Maybe the “References” submenu on the left bar gets moved up above the fold.
Last thing — I think that there’s an additional UI problem that makes it hard to find the docs. I’ll walk you through the flow here so you can replicate the problem in your browser because it’s kind of hard to explain:
1. https://www.pulumi.com/ ->
2. https://www.pulumi.com/docs/ ->
3. Put your mouse in the middle of the page and scroll down to the footer
a. Now, look at the left sub-menu column. It’s cut-off (unless you have a huge browser window). The “References” section is beneath that cut-off.
b. The only way to get to “References” is to put your mouse over the left sub-menu and scroll down within that menu. That is not obvious unless you know that’s a scrollable container.
I think that last point is likely why I end up so lost so frequently. I click “Docs” and I look around for what I’m trying to find, but I don’t see it. It wasn’t actually until today (as I was writing this) that I realized that the left bar could scroll. If I’ve done it before, it’s not even an action that I registered.
I love the product, and I hope that’s helpful. It’s all meant in the spirit of feedback and not complaining.
03/09/2022, 12:26 AM
thank you for writing up this detailed feedback!! the left nav interactions and scrolling is definitely something we want to fix soon, it's a very frustrating experience!
for the reference api docs id encourage you to head directly to pulumi.com/registry instead of by way of the docs. you can find a link to this on the very top right of the website.
we are also overhauling the docs landing page to make it easier to quickly get to the registry.