Hello friends! I'm an engineer on the Pulumi docs team and we're going to be spending some time this quarter making some improvements to our provider docs in the Registry (e.g., pages like these). We have a good-sized list of improvements to make already, but I'd really love to gather up some ideas from you all as well. What are your biggest pain points today when you work with these docs? What could we do better? Any and all suggestions welcome -- either here or feel free to hit me up in a DM. Thanks in advance!

@miniature-musician-31262 the biggest issue for me right now is that there is no fast and especially local (!!) way to test the docs generation for a provider, like with the Terraform providers. Fiddled around with

pulumi-registry

,

pulumi-hugo

and

pulumi-docs

to get local workflow running, but wasn't successful. So right now you can push a new provider version and hope that the associated GitHub Workflow in

pulumi-registry

will run without errors and create a correct documentation. Because the workflow only runs twice a day, it really slows down developing (or wrapping) a new provider version. I patched

registrygen

to have it run completely locally so that I can at least be sure that the generation process will be run without errors. How the docs will look like is currently out of scope.

My pain point is having a single point of entry / link-list place that can get me into / between provider docs and Pulumi SDK docs. I want to be able to get from (e.g.) the Vpc API docs to the

pulumi.all()

docs quickly. Right now, I need to start from two places, the registry and https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/pulumi/

Yes! Both of these are excellent suggestions and I strongly agree on both.

I have a suggestion very specific to Azure Native (although it might be interesting to have something similar for other native providers) : For each Azure Native Resource documentation page in the Pulumi Registry , have links on the page link to the corresponding resource in Bicep documentation and the corresponding Azure REST API endpoints documentation. For instance with Azure Web App : Pulumi doc ➡️ https://www.pulumi.com/registry/packages/azure-native/api-docs/web/webapp/#azure-native-web-webapp Microsoft doc (Bicep) ➡️ https://learn.microsoft.com/en-us/azure/templates/microsoft.web/sites?pivots=deployment-language-bicep Azure API doc ➡️ https://learn.microsoft.com/en-us/rest/api/appservice/web-apps?view=rest-appservice-2022-03-01 What would be even better in adition to that would be to have a tab "Pulumi" on the Microsoft documentation alongside with the ARM, Bicep and Terraform tabs. I don't know if you can talk to Microsoft about that but it would be great to have for each resource a tab indicating what the code looks like for each IaC solution. I already mentionned that previously but that may not be that easy to convince Microsoft

Have the "Table of contents" left sidebar automatically scroll to the module/category you are browsing

Yes, a docs-only search would be great.

These are great suggestions, thank you! 🙌 You’ll be happy to know we’re already working on all of them but the syntax highlighting and docstring links. I’ll bring those to the team as well!