👋🏻 im susan a ux designer at Pulumi and i am looking for folks that have had a frustrating experience using our docs. id love to do a quick 15-minute zoom call to hear about your experience. ill use your information to help guide improvements to our docs. if ur interested add an emoji to this message and ill reach out in dm to schedule something. thank you!!

Sorry, I use your docs as example of how organized and intuitive docs should be. But from the questions that I see and help answer here it seems a lot of newcomers do not reach the documentation regarding the model and how the `Output`s work and how to transform them. I think it is because those types are "_hidden_" on the packages docs, which help those who already use Pulumi a lot by not adding the exact same information and links on every page, but may be confusing if you reach the docs for the package before the docs for the programming model (honestly at least I personally like to try for myself before reading the entire documentation, so I can understand this scenario).

@brainy-church-78120 I have one remark, that relay think should be addressed… take a look at the result of this search query: https://www.pulumi.com/docs/search/?q=Domain - you’l get a list of about 17 references to

Domain

, but unfortunate one does not have any context where the according reference belongs to. e.g. is it the link to the Azure, AWS or Linod doc? even within azure there are multiple

Domain

types which could be used: domainregistration, eventgrid or eventhub? It would really make tings easier to find if the result list would give some more context to each record found.

The ToC on the right-hand side only has 2 levels of depth. When in a large document, sometimes it’s unclear what section you’re in when looking at methods and properties. https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/pulumi/x/automation/#LocalWorkspace-removeConfig Also, it would be nice if the types were called out somehow in the sidebar.

Hey, @brainy-church-78120 I think the docs could benefit from some more examples and for a section on debugging/troubleshooting.

Regarding docs having examples: https://github.com/pulumi/docs/issues/4507 Import docs will be added as that is the current work item for me

I see. Thanks for pinging me on that issue.

The indentation of the Classes -> Methods -> Parameters / Returns. Makes it more difficult to read. Maybe color differences as well. Compare a long page: https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/awsx/ec2/ with boto3: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/eks.html