[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

Beta Give feedback

1. Begin measuring and publishing example-conversion metrics
2. Begin measuring and publishing content ingestion quality, including imports
3. Identify and incorporate any existing high-value issues related to docs content quality
4. [Epic] Switch all tfgen uses to the new converter pulumi-terraform-bridge#1280
   kind/engineering resolution/fixed +2
   
5. Indicate alongside examples whether they compile and/or preview successfully
6. Customer Request: Bug: tfgen does not include descriptions for nested config fields pulumi-terraform-bridge#1045
7. Import section of AWS Classic resources is broken - showing TF import statements pulumi-terraform-bridge#1344
   area/docsgen kind/bug p1 resolution/fixed +4
   
8. Service account import issues pulumi-gcp#1375
   area/docs kind/bug resolution/fixed +3
   

Q3: Core team

Beta Give feedback

1. Unresolved references don't look right in generated code pulumi#14463
   area/codegen kind/enhancement +2
2. Broken YAML generated by the converter pulumi-yaml#539
   kind/bug resolution/fixed +2
   
3. Programgen issues prioritized by top 50 pages (based on page views)
4. Customer Request: Display Fully Qualified Type Names in Python Generated Documentation pulumi#15137
5. Registry Docs Enhancement: Update the "Create Resource" section to generate a complete syntax reference for each language pulumi#14675
   area/docs kind/enhancement resolution/fixed +3
   

Q3: Docs team

Beta Give feedback

1. Cross-package API dependencies don't render correctly pulumi#12765
   area/codegen area/docs customer/lighthouse kind/bug resolution/fixed size/M +6
   
2. https://github.com/pulumi/home/issues/2725
3. [Epic] Decouple provider API docs generation from pulumi/pulumi #3834
   2 of 7
   kind/engineering size/L +2
4. Registry Docs Enhancement: Update the "Create Resource" section to generate a complete syntax reference for each language pulumi#14675
   area/docs kind/enhancement resolution/fixed +3
   
5. Render updated syntax on docs pages pulumi#15393
   area/docs kind/enhancement resolution/fixed size/M +4
   
6. Add end-to-end tests to validate page structure for common resources #3907
   8 of 8
   area/api-docs kind/engineering resolution/fixed size/S +4
   
7. [Epic] Property rendering issues in the API docs #3906
   4 of 7
   +0
8. insufficient documentation to make use of import #3039
   area/docs kind/codegen resolution/fixed +3
   
9. Automate building and publishing of related-resources lists #3923
   area/api-docs kind/enhancement +2
10. Fix existing issues related to the API docs nav (scroll positioning, others)
11. Add links to relevant blog posts on registry page side bar #3914
    area/docs kind/enhancement +2
12. Reorder the main content sections on resource pages (blocked on description, examples, and imports fields)

Q4: Core team

Beta Give feedback

1. Extend schema to allow dedicated "examples" and "import" sections
2. 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

Beta Give feedback

1. Document overlays
2. Update the Registry front-end to capture quantifiable API docs feedback/satisfaction
3. Gather requirements for handling multiple Azure/ARM API versions
4. Spike on supporting docs for multiple provider versions

Q4: Providers team

Beta Give feedback

1. TF docs translation bug pulumi-aws#2427
   area/docs kind/bug +2
2. Language chooser is missing on Registry docs pages pulumi-terraform-bridge#926
   area/docsgen kind/bug resolution/fixed +3
   
3. aws.ec2.vpc: Examples are missing headings pulumi-terraform-bridge#847
   area/docsgen kind/bug resolution/fixed +3
   
4. Arguments duplicate second line of source content pulumi-terraform-bridge#553
   area/docsgen kind/bug resolution/fixed +3
   
5. Inline links in resource property descriptions are not linked. pulumi-terraform-bridge#351
   area/docsgen kind/bug +2
   
6. Display error with API Documentation for the AWS Lambda Function Resource pulumi-aws#2624
   area/api-docs area/providers kind/enhancement resolution/fixed size/L +5
   
7. The title of the DatabaseUser's example code just says S pulumi-mongodbatlas#165
   area/docs kind/bug +2
   
8. Examples into code tabs pulumi-terraform-bridge#1530
   area/docsgen kind/bug resolution/fixed +3
   
9. SQS Queue docs look wrong pulumi-aws#3100
   area/docs kind/bug resolution/fixed +3
   
10. Property descriptions are not correctly parsed pulumi-signalfx#377
    area/docs kind/bug resolution/fixed +3
    

Out of scope

Beta Give feedback

1. [Tracking Issue] Incorrect API Docs pulumi-terraform-bridge#1292
   area/docsgen kind/epic resolution/duplicate +3
   
2. [Tracking Issue] Missing Generated Documentation pulumi-terraform-bridge#1290
   area/docsgen kind/epic resolution/duplicate +3
   

[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 pulumi/pulumi#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 pulumi/pulumi-terraform-bridge#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.