Document recommended project layout structures

[joeduffy]

We should document best practices for how to organize a single project: where to put files, how to break them apart, how and when to use sub-modules, the advantages and disadvantages to different approaches, etc. I'm not certain we need to be very prescriptive here -- similar to how we leave the question of project/stack granularity open-ended -- but we should help guide folks through the decision-making.

In general, the best practice we recommend are similar to those for the language you've chosen (so you might get some good information by searching for "organizing Python projects" (or whichever language)), but there are definitely some Pulumi-specific concerns that are worth calling out, like config, resource-specifics like IAM versus networking versus higher-level services, where to put application code if it's being managed alongside infrastructure code, etc.

We do have documentation on recommended layouts at the "macro" level: how to organize your projects, stacks, and how to depend on a different project/stack from another. For example, this user guide and this blog post which dives into a more real-world AWS example. The two pieces of content would be highly complementary to one another.

[aureq]

Regarding not being "too prescriptive", my experience at both AWS and Google tells me otherwise. Many customers I have met complained that vendors aren't prescriptive or specific enough of what they view as best practices (K8s being the worst of all). As a former architect, I spent many hours explaining educating customers on these best practices (It's awesome when you see a light-bulb moment with one of your customers though). I also think it's important to give a roadmap (or some guidance) on the priority of adoptions of these best practices. For example, Pulumi secrets should be part of Day 1, Stack references part of Day 2 or 3 along with Policy-as-Code, and module repositories happening later with good code documentation.