Reorganize "Examples" repo to make it easier to find content

[stack72]

Proposal

This repository has continued to grow and it's becoming more difficult to find examples that are specific to your usecase. I am very much of the belief that when a user comes to Pulumi to find information on using Pulumi with Python, then we want to make that easier for them to find than to scroll through an infinite list of folders.

• Python
• DotNet
• Go
• TypeScript/Javascript

the top level folders would related to our Pulumi language runtimes. This means it's nice and easy to point to https://github.com/pulumi/examples/tree/master/python

Inside each of the languages, we would have a list as follows:

• AWS Resources
• GCP Resources
• Kubernetes Resources
• other cloud / provider resources e.g. equinix metal
• Automation API
• Policy Packs
• Testing (unit / integration)

I believe this structure, will allow users to find concepts much easier e.g. "AWS Python".

The work involved here is pretty trivial - BUT we would need to ensure that we updated any guides / blog posts / tutorials for the specific example. Each of the language folders can then have a README in it that can list the "getting started" material with links to that specific example. We can also easily ensure that each language has a set of "getting started" examples across our major providers. We can use a combination of badges to show that information as well as other useful information like a "supported" (i.e. it's run in CI nightly) example

[MisinformedDNA]

Grouping by language over cloud seems correct since developers might use multiple clouds, but they'll probably use a single language and individual developers are unlikely to code in multiple languages for the same cloud.

The only downside is that a given example might only be available in one language, but still could be helpful as a reference. To put a wrench in your side, what if the order went "Cloud > Example > Language"? On the converse, this would also make it less necessary to create every example in each language. Just thinking.

[mastoj]

The structure now is definitely not optimal that is for sure and this would be a step in the right direction.

With that said, if you change perspective some people (like myself) don't come to see how to do it specifically with language X since the language itself might not have examples for everything that is possible to achieve. For example, let's say I'm interested in configuring API management using golang but there is only example in .net and typescript, organizing it around language might give an impression that the feature isn't there. However, focusing on the resources first you can always find an example and then you might be able to adopt it to your language.

You will always find people that will argue one way or another, I just thought I would share a different point of view for the sake of the discussion.

[mastoj]

Ideally it would be nice if it was possible to "tag" folders in github or something.

[tenwit]

I use the examples repo almost exclusively via the GitHub UI rather than cloning it, and that colours my opinions. The landing page of the example repo has a lot of scrolling, but that's much faster than navigating through multiple levels of directories, imo. I'd prefer to not add two extra levels of nesting (e.g. changing aws-cs-eks to aws/cs/eks).
I think the docs are well laid out, with all packages at the same level, and you pick a language without changing level (cf. https://www.pulumi.com/docs/reference/pkg/). The repo could get closer to that model by adding one extra level (e.g. aws-cs-eks to aws-cs/eks). The top level would have the package-and-language.

Though I don't use it this way much myself, if I were to clone the repo, I'd be most interested in just a single language. From that point of view, the simplest user experience would be to split the repo by language (examples/aws/cs/eks to examples-cs/aws/eks), and not group languages within a single repo. That might be more effort than it's worth though, and it doesn't really mesh with my preferred webUI experience :)

[shahiddev]

Agree that the current structure is not great and it would help to restructure.
At first glance I can't see any strong reasons to choose language then provider vs provider then language.
However reflecting on this a bit and this is probably just my approach to things but I think I'd prefer provider then language. The reason is I'm often looking to solve a particular problem, i.e. How do I do x with this provider, if I don't find an example for my language I can still look at other language examples, for that provider, and elucidate what it might be for my language.

[imod]

regardless of the structure, I think there should also be some kind of an index for solutions belonging more to a concept then to an actual provider. e.g. the provisioner implementation at https://github.com/pulumi/examples/tree/master/aws-ts-ec2-provisioners - I don't do anything with AWS, but the concept is not bound to AWS and I can use it easily with Azure or anything else. To find such an example, It would probably also make sense to have such things linked/tagged within the root folder of the repo or have some other way to list them.

[ringods]

A number of arguments are already given: also at our company we only use a single programming language to develop our Pulumi code. As a result, I would favor the programming language as the top level differentiator.

One argument for not taking the different clouds as the top level: I treat every Pulumi provider the same, whether that is a major cloud provider or the MySQL provider. Which will you pick and which not? The examples for me are there more to show specific Pulumi features (parent, transformations, ...) in the different languages, than they are there to show off on every possible resource of every possible provider.

Like @mastoj, I do not clone this repo, but browse through it via the Github web UI. A well designed README at the top, extended by README in subfolders can help in decoupling the further subfolder structure. With sections and tables in the README, you can have nested structures below but all still directly accessible from the README to prevent clicking too much times.

At least try to limit the amount of folders at the levels which contain a README because the repository content shifts the README preview down beyond the fold.

[Graham-Beer]

My opinion is provider first then the language, i.e.
AWS
        - NodeJS
        - Python
        - .NET
        - GO
Azure
        - NodeJS
        - Python
        - .NET
        - GO

Could break it down further by adding the service after provider, which would look clean, but could be more time consuming to setup:
AWS
    - EC2 build
            - NodeJS
            - Python
            - .NET
            - GO
    - Lambda
            - NodeJS
            - Python
            - .NET
            - GO

[rawkode]

There’s some great opinions here! I’m definitely in the camp that language first, then provider.

I tend to use a single language, as I suspect most teams do. However, I do value looking at examples across providers, even when not using them. So definitely echoing my support for language -> use case.

[ringods]

Bumped into this today: browsing the examples in VSCode in your browser is very easy via this URL:

https://github1s.com/pulumi/examples

Backing project: https://github.com/conwnet/github1s

[sanmai-NL]

Symlinks can be used to offer various alternative structures.

[jfmatth]

Let us make sure we don't lose sight of the fact, we want the README to show up near the top so people can understand how to use it. OR, we could link back to instructions on how to use each example, but that seems like a LOT more work 😮