Programming model reorganization #4707
Conversation
|
Your site preview for commit ed1c1e9 is ready! 🎉 http://pulumi-docs-origin-pr-4707-ed1c1e9e.s3-website.us-west-2.amazonaws.com. |
![pulumi[bot]](https://avatars.githubusercontent.com/in/15540?s=60&v=4){kind=small}
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
|
Your site preview for commit 57a8d1e is ready! 🎉 http://pulumi-docs-origin-pr-4707-57a8d1e2.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
~ www.pulumi.com aws:route53/record:Record update
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
davidwrede
force-pushed
the
spara/programming-model-rewrite
branch
from
57a8d1e
to
eba9bc5
Compare
|
Changes in this PR include the following:
|
|
Your site preview for commit eba9bc5 is ready! 🎉 http://pulumi-docs-origin-pr-4707-eba9bc56.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
davidwrede
force-pushed
the
spara/programming-model-rewrite
branch
from
eba9bc5
to
34197c9
Compare
davidwrede
changed the title
|
Your site preview for commit 34197c9 is ready! 🎉 http://pulumi-docs-origin-pr-4707-34197c9a.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
|
@davidwrede How intentional is the ordering of the items under Architecture & Concepts? I only ask because I'm so used to seeing Projects, Stacks, Config and Secrets all clustered together (and they make conceptual sense ordered in that way, and you can mostly read them in that order -- with the exception of Programming Model of course, which is much more complex) -- whereas here, the ordering isn't quite as clear to me. Again, I'm probably just so used to seeing it the way it is now that I'm not seeing the intent behind the new presentation, so if you could shed a little light, that might help. |
|
It's fairly intentional, but open for debate. :) The existing left nav items are listed in the order you stated; however, within the programming model topic it goes in a different order (i.e. Resources (both custom and component), Inputs and Outputs, then Secrets, Config, etc.). Since this PR is about refactoring content out of the Programming Model topic and putting like content together, I had to try and figure out which structure to use. The result is a meld of both organizational structures together mixed with how I felt the order should be for a new reader (i.e. it feels like you need to talk about resources before talking about stacks or configuration, for instance). The order is also reinforced via the diagram (and the text below the diagram) on the Architecture & Concepts page. So, if the order doesn't make sense (or needs tweaking), I'm open to changing it, but I'd like the new ordering to follow the same convention of organizational reinforcement in the left nav, diagram, etc...or at least as close as possible. |
There was a problem hiding this comment.
A first pass of feedback. Great to see the progress here!
A high level comment on the changes, which I noticed from several points of view as I started reviewing this.
Previously - the Programming Model topic was at least logically an overview of the programming model - the code you write in a Pulumi program to accomplish various things. It was effectively the reference docs for the core @pulumi/pulumi SDK. That fact had already been a little obscured by the addition of the https://www.pulumi.com/docs/intro/concepts/programming-model/#programs section at the top of that page - but the bulk of the content in the page which was under https://www.pulumi.com/docs/intro/concepts/programming-model/#pulumipulumi in the nav was documentation of the core SDK. Any change to the core Pulumi SDK required updating this page, and any question about code you write to accomplish something in Pulumi was answered in this page.
Other pages in the architecture and reference section covered other things that weren't part of the SDK directly - like Project, Stacks, Backends, etc. These all cross-referenced the relevant docs in the SDK and vice versa. Changes to the CLI generally required updating these docs.
In the rewrite here - the SDK documentation has gotten mixed in with conceptual documentation. There are pros can cons to that - though on balance I'm inclined to agree it's a good thing. Many of my points below are ultimately related to how this change leads us to maybe rethink things about content in this section.
How intentional is the ordering of the items under Architecture & Concepts?
I similarly found the TOC a little awkward. Some of that is a natural consequence of the structural change noted above - though I think we can likely map things such that this still works well. I personally like the order in the current Programming Model TOC - but it needs to be augmented here with some of the non-programming-model topics. My suggestion would be:
- Projects
- Stacks
- State and Backends
- Resources
- Components
- Inputs and Outputs
- Config
- Secrets
- Assets and Archives
- Runtime Functions
(and moving or rethinking "How Pulumi Deploys Infrastructure" and "Organizing Projects and Stacks" as noted in other comments)
|
Your site preview for commit ad6a225 is ready! 🎉 http://pulumi-docs-origin-pr-4707-ad6a2258.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
|
Your site preview for commit afe29c5 is ready! 🎉 http://pulumi-docs-origin-pr-4707-afe29c56.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
|
Most tech review feedback has been incorporated. The only remaining feedback to incorporate is around the programming model text on the root "Architecture & Concepts" landing page, so I'll submit a commit for review by early next week. |
|
Remaining TR feedback has been incorporated. I also tightened up a couple sections and fixed some remaining broken links in the blogs. |
davidwrede
force-pushed
the
spara/programming-model-rewrite
branch
from
8bb8dc2
to
afda87b
Compare
|
Your site preview for commit afda87b is ready! 🎉 http://pulumi-docs-origin-pr-4707-afda87b3.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
~ www.pulumi.com aws:route53/record:Record update
|
Your site preview for commit 9b8bbfa is ready! 🎉 http://pulumi-docs-origin-pr-4707-9b8bbfad.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
There was a problem hiding this comment.
@davidwrede Some initial feedback on Projects and Stacks for ya.
Co-authored-by: Christian Nunciato <c@nunciato.org>
Co-authored-by: Christian Nunciato <c@nunciato.org>
|
Your site preview for commit 2029ca6 is ready! 🎉 http://pulumi-docs-origin-pr-4707-2029ca67.s3-website.us-west-2.amazonaws.com. |
1 similar comment
|
Your site preview for commit 2029ca6 is ready! 🎉 http://pulumi-docs-origin-pr-4707-2029ca67.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
|
Your site preview for commit 5f340b8 is ready! 🎉 http://pulumi-docs-origin-pr-4707-5f340b8a.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit c70564b is ready! 🎉 http://pulumi-docs-origin-pr-4707-c70564be.s3-website.us-west-2.amazonaws.com. |
1 similar comment
|
Your site preview for commit c70564b is ready! 🎉 http://pulumi-docs-origin-pr-4707-c70564be.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
~ cdn aws:cloudfront/distribution:Distribution update
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
~ cdn aws:cloudfront/distribution:Distribution update
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
|
Your site preview for commit 5f340b8 is ready! 🎉 http://pulumi-docs-origin-pr-4707-5f340b8a.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
|
Your site preview for commit adcd8f0 is ready! 🎉 http://pulumi-docs-origin-pr-4707-adcd8f05.s3-website.us-west-2.amazonaws.com. |
There was a problem hiding this comment.
🍹 The Update (preview) for stack pulumi/www.pulumi.com/production was successful.
Resource Changes
Name Type Operation
* origin-bucket-policy aws:s3/bucketPolicy:BucketPolicy replaced
~ cdn aws:cloudfront/distribution:Distribution update
|
@cnunciato I've implemented most of your changes (and addressed next steps for the ones that can be done after this PR is merged). |
|
Site previews for this pull request have been removed. ✨ |
Reorganize the programming model to make to make it more accessible.
The material has been reorganized to present the Pulumi concepts with definitions first and provide a high level overview how the pieces work together. This is different from the current model where users are stepped through the process while introducing the concepts. The content has been divided into sections to make it easier to maintain the document.
Update: See follow up comment on changes. The content in this PR is now ready for review.