[Epic] API Docs Q3/Q4 Improvements

[cnunciato]

This issue tracks the work we'll be doing in Q3 and Q4 to improve our API docs-generation processes, content quality, and overall user experience.

Project doc: https://docs.google.com/document/d/181uKD8zfVF3m_VkehQdhPYQ88r9AGog5X7wHjXo6_YY/edit

### Q3: Providers team
- [ ] Begin measuring and publishing example-conversion metrics
- [ ] Begin measuring and publishing content ingestion quality, including imports
- [ ] Identify and incorporate any existing high-value issues related to docs content quality
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/1280
- [ ] Indicate alongside examples whether they compile and/or preview successfully
- [x] Customer Request: https://github.com/pulumi/pulumi-terraform-bridge/issues/1045
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/1344
- [ ] https://github.com/pulumi/pulumi-gcp/issues/1375

### Q3: Core team
- [ ] https://github.com/pulumi/pulumi/issues/14463
- [ ] https://github.com/pulumi/pulumi-yaml/issues/539
- [ ] Programgen issues prioritized by top 50 pages (based on page views)
- [ ] Customer Request: https://github.com/pulumi/pulumi/issues/15137
- [ ] https://github.com/pulumi/pulumi/issues/14675

### Q3: Docs team
- [ ] https://github.com/pulumi/pulumi/issues/12765
- [ ] https://github.com/pulumi/home/issues/2725
- [ ] https://github.com/pulumi/registry/issues/3834
- [ ] https://github.com/pulumi/pulumi/issues/14675
- [ ] https://github.com/pulumi/pulumi/issues/15393
- [ ] https://github.com/pulumi/registry/issues/3907
- [ ] https://github.com/pulumi/registry/issues/3906
- [ ] https://github.com/pulumi/registry/issues/3039
- [ ] https://github.com/pulumi/registry/issues/3923
- [ ] Fix existing issues related to the API docs nav (scroll positioning, others)
- [ ] https://github.com/pulumi/registry/issues/3914
- [ ] Reorder the main content sections on resource pages (blocked on description, examples, and imports fields)

### Q4: Core team
- [ ] Extend schema to allow dedicated "examples" and "import" sections
- [ ] Pull examples and resource imports content out of the `description` field (blocked by `Extend schema to allow dedicated "examples" and "import" sections` above)

### Q4: Docs team
- [ ] Document overlays
- [ ] Update the Registry front-end to capture quantifiable API docs feedback/satisfaction
- [ ] Gather requirements for handling multiple Azure/ARM API versions
- [ ] Spike on supporting docs for multiple provider versions

### Q4: Providers team
- [ ] https://github.com/pulumi/pulumi-aws/issues/2427
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/926
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/847
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/553
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/351
- [ ] https://github.com/pulumi/pulumi-aws/issues/2624
- [ ] https://github.com/pulumi/pulumi-mongodbatlas/issues/165
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/1530
- [ ] https://github.com/pulumi/pulumi-aws/issues/3100
- [ ] https://github.com/pulumi/pulumi-signalfx/issues/377

### Out of scope
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/1292
- [ ] https://github.com/pulumi/pulumi-terraform-bridge/issues/1290

[iwahbe]

On the providers list is: Add variable declarations for undefined references in bridged provider examples. I'm not 100% sure where this work should go, but my intuition is that we want these kind of transforms to happen at the PCL level, which implies the work item should be moved to the IaC Core team.

CC @justinvp @Zaid-Ajaj

[iwahbe]

We discussed implementing Enable documentation of provider overlays at the regestrygen level, not as part of individual providers. If this is done by providers, we will need schema support, since that is the only artifact we emit for docs generation. CC @cnunciato

[iwahbe]

• [ ] Add and populate a new field to the schema for copyable resource constructors
• [ ] Add and populate a new field to the schema for copyable lookup functions

Why do these need to be new schema fields? I thought the plan was that docsgen derived these from the existing schema.

[justinvp]

• [ ] Explore/spike on generating copyable resource constructors (minimal and complete)
• [ ] Explore/spike on generating copyable lookup functions

I think both of these are covered by https://github.com/pulumi/pulumi/issues/14675

[justinvp]

• [ ] Add and populate a new field to the schema for copyable resource constructors
• [ ] Add and populate a new field to the schema for copyable lookup functions

Why do these need to be new schema fields? I thought the plan was that docsgen derived these from the existing schema.

Yeah, I don't expect we need anything new in the schema for these.

[iwahbe]

@cnunciato @justinvp I have edited the issue lists to move some items to their appropriate teams. That was mostly moving items from the Providers team to the IaC Core team.

[lukehoban]

Let's pull the items in https://github.com/pulumi/pulumi-terraform-bridge/issues/1291 into this Epic (identifying which layer of the stack each need to be fixed).

[iwahbe]

Let's pull the items in pulumi/pulumi-terraform-bridge#1291 into this Epic (identifying which layer of the stack each need to be fixed).

That issue tracks formatting issues introduced by the bridge scraping process, so the bridge's docs generation is the layer of the stack where each of these bugs should be fixed.

[cnunciato]

Closing this out as we're no longer working this epic, but leaving remaining issues open to be picked up later.

[pulumi-bot]

Cannot close issue:

• does not have required labels: resolution/

Please fix these problems and try again.