https://pulumi.com logo
Title
w

white-balloon-205

03/31/2020, 11:12 PM
We know that resource documentation is one of the most important areas of the Pulumi docs site for most Pulumi users, and we've heard the feedback that there is room to improve on these resource docs! Yesterday, we took a major step on rolling out a brand new approach to resource docs for Pulumi. 🎉 These new docs are resource-oriented instead of API-oriented, and are presented as a single page per resource for easier reading, discovery, and navigation. They also support switching on different Pulumi languages inline. API docs for each language are still available, and are deep-linked into from these resource docs. But in general we expect to lead with these resource-oriented docs throughout our content as canonical, language-agnostic reference for each Pulumi resource. We've rolled out these new docs so far for AWS, Azure and GCP, with the rest of the providers on their way soon. We're also continuing to work on many more improvements on top of these new docs, so expect to continue to see improvements over the coming days and weeks. (Before you ask - Kubernetes docs are coming next!) We'd love your feedback on the new docs either in #docs, in GitHub, or via the 👍/👎 buttons on the site. Here are a few pointers: • An example resource: https://www.pulumi.com/docs/reference/pkg/aws/sqs/queue/ • AWS package: https://www.pulumi.com/docs/reference/pkg/aws/ • Azure package: https://www.pulumi.com/docs/reference/pkg/azure/ • GCP package: https://www.pulumi.com/docs/reference/pkg/gcp/ • Root API reference with links to all of these: https://www.pulumi.com/docs/reference/pkg/
😛artypus: 8
👍 9
😍 5
🎉 15
Here's a birds-eye view of the new content layout.
g

great-byte-67992

04/01/2020, 3:14 AM
This approach is fantastic. Is there anyway to consume the documentation template as a library author for my `ComponentResource`s?
w

white-balloon-205

04/01/2020, 3:18 AM
@great-byte-67992 not yet - but we will be adding that! This documentation is all driven off of a new canonical language-agnostic schematization of the Pulumi resource model. That schema doesn’t yet represent component resources, but we’ve designed it with the intention to extend to components in the near future.
g

great-byte-67992

04/01/2020, 3:24 AM
That’d be amazing. I’m currently using mkdoc + typedoc for kloudlib but i’d love to use something that feels more pulumi native so that users can get a consistent documentation experience.
b

boundless-airport-99052

04/01/2020, 7:55 AM
The new doc is very clear ! Great improvement 👍 I’ll add below some feedbacks
Page naviguation
👍 1
I think also that right menu could be improved. Current menu :
👍 1
resources, datasources and types are mixed
👍 1
I’d prefer (my opinion) something like:
- Virtual Machine resource
    - Arguments
    - Outputs
- Data sources
   - Lookup…
   - …
- Supporting types
c

cool-egg-852

04/01/2020, 2:36 PM
https://www.pulumi.com/docs/reference/pkg/ still has the issue of calling everything a cloud provider.
w

white-balloon-205

04/01/2020, 2:41 PM
@cool-egg-852 out of curiosity - what name would you prefer to see used here?
c

cool-egg-852

04/01/2020, 2:41 PM
Just like TF, everything is a provider, then you have major cloud, cloud, infrastructure software, network, vcs, database, etc.
w

white-balloon-205

04/01/2020, 2:44 PM
@boundless-airport-99052 thanks for the notes. On the “navigation” point - is that about wanting anchors on the headers so you can deep link to them? On the nav structure - we could definitely add some more structure there. Note though that the “Loookup” section is not about “data sources” (in the Terraform sense) but about resource getters. The “data sources” are on separate pages listed under “functions”.
@cool-egg-852 understood - we will be significantly restructuring that main reference docs landing page as we roll out the remaining new reference docs pages and will be looking to add some more substructure around the list of all providers. Thanks.
👍 1
b

boundless-airport-99052

04/02/2020, 2:26 PM
Hi @white-balloon-205, I don’t think that we currently can select a specific version of the provider doc. For example, there lot of changes between azure provier 1 and 2, and people on version 1 will not understand why the doc is not sync with their version.
w

white-balloon-205

04/02/2020, 3:52 PM
@boundless-airport-99052 Yes - that is right - we currently just have a single version synced with the latest released version. We would definitely like to be able to show other versions as well - especially when there are significant major-version bumps like with Azure. This is something we'll be adding after the initial wave of work on these new docs.
👍 1