Refactor /docs/intro/concepts/programming-model

[isaac-pulumi]

Problem

/docs/intro/concepts/programming-model has high traffic and high bounce. It is a very long doc that could be broken up into to improve discoverability, readability, and SEO.

Proposed solution

Pending doc/UX review:

• (1) Summary page with links to relevant sub-pages

• (1) Sub page for "Pulumi Programs"

• Break out each section in "Pulumi SDK" into its own page

• Fix Add note clearly describing current limitations of dependsOn #4531 as part of this work

• Confirm that all new pages render appropriately on Android (per original report in Programming model docs not fully loading on mobile #3601)

[lukehoban]

Is this the same issue tracked in #3249?

[joeduffy]

I would also strongly suggest being deliberate about what is essential, informational, and reference material. We tend to intermingle these three freely and the ordering is a bit off. It would be better to lead in with the essential concepts and do a great job of explaining them succinctly, linking to further informational documentation for deeper dives.

For example, inputs and outputs, resources, configuration and secrets, etc, are critical to anybody doing Pulumi programming -- however, detailed documentation for every one of the available resource options, and/or shapes of dynamic provider APIs, certainly are not, and would be better put into detailed documentation pages for those topics, respectively.

[isaac-pulumi]

@joeduffy this makes sense and appears to be in-line with some of the feedback in #3249 as @lukehoban points out.
That issue pointed out projects and stacks (current docs for those areas need work too).
#4585 is also relevant here as well.

[spara]

Splitting up the docs and a several passes of rewrites are already completed. I need a week to make another pass and to move it from Google Docs to markdown. The tradeoff is that I need to defer the next Automation API blog post for a week to accomplish this.

[lukehoban]

Splitting up the docs and a several passes of rewrites are already completed.

Note that if this work has happened offline, there have been 10 or so fixes to the programming-model page in the last week which we'll need to make sure to incorporate in.

[spara]

I'll make sure they're included