Hello friends! I'm an engineer on the Pulumi docs ...
# docs
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
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
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
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
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
Make docs for additional API versions browsable - I'm constantly browsing the SDK in my IDE for exploring parameters for those
Maybe this is a suggestion towards specific provider SDK teams but it would be awesome to have a direct link back to docs for a given resource within the docstring in the SDKs
Improve syntax highlighting in code examples – see comparison between IDE and docs
And if relevant here.. Consider disabling search engine indexing on the auto generated Pulumi AI answers or at least lowering priority if possible on those pages until these actually reference actual API modules. There's massive amount of hallucination and even dangerous misconfigurations I've come across in those. https://www.pulumi.com/ai/answers
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!