I think it's a genuinely tough problem. Keeping documentation up to date is a Sisyphean task - it's great that Amazon has managed to to some extent, but it's hella difficult for small teams.

There's some amount that can be answered by providing a 'beaten path' for people to walk, but a) discoverability is a problem - people often don't know the right keyword to search for to find what they need, and b) people are often subtly off the beaten path, and need some adaptive guidance to their particular situation.

AI answers are great for both of these problems.

> I would love to see them publish some curated Terraform examples as well given how better IaC is compared to manual actions

I imagine they'd rather you use CloudFormation?

:s/CloudFormation/CDK/, but yes :)

My $0.02 cent is use boto3 if you're working in Python. It's gross, but stable. When I built my CD service I went with boto3 because CDK had 10x the issues on GitHub. Not an exact comparison since the CDK repo seems to include more than one language, but still. Skipped Terraform because it took three months to merge a two line bugfix I submitted, has a similarly massive number of issues, and to this day it still doesn't seem to support some critical API endpoints.

boto3 is an SDK for the AWS API, CDK is an SDK for CloudFormation. boto3 is imperative, CDK is declarative. You can do CDK-like things _in_ boto3, but past a certain level of complexity you'll end up reimplementing so much functionality that you would have done better to just learn enough to use the CDK.

Comparing issues is particularly irrelevant in this case since (as you say) the boto3 API is pretty much stable (since it is "just" a language-specific client to an established API), whereas there are regularly requests for higher-level Constructs in CDK.

Terraform is also declarative but I don't see how that negates the issues. I learned first-hand that the Terraform plugin and CDK being riddled with more than 3.7k and 1.7k bugs/tasks respectively was highly relevant. That's a mountain of work to be done for what are both essentially API wrappers! A lot of operations also don't fit nicely into the declarative model, so Terraform in particular doesn't even support a lot of operations. boto3 being procedural does mean an added step for checking existing state when updating resources, but that's a minor tradeoff for stability in mission-critical code. I would love to see CDK become less buggy though!

> That's a mountain of work to be done for what are both essentially API wrappers!

You are once again assuming that the existence of feature requests implies that the existing tool is not fit for purpose. This simply isn't the case. The boto3 SDK "only" attempts to provide a client for the AWS API - feature requests are essentially meaningless until/unless a new AWS Service is launched. The nature of CDK (or Terraform), however, is that "higher-level" constructs can be created - Constructs defining patterns, rather than just one-to-one mappings with AWS Resources. These can be imagined and requested essentially infinitely; but those requests doesn't mean that the existing L1/2 Constructs are incomplete or flawed.

Candidly, to describe CDK/Terraform as "essentially API wrappers" betrays the fact that you didn't really try to use them seriously. Yes, they call AWS APIs under the hood; but if you're only using them as a drop-in replacement for boto3 calls, you are missing out on a lot of the power they provide.

> A lot of operations also don't fit nicely into the declarative model

Cool, in which case, boto3 is indeed the correct choice. But that's because it's the right tool for the job, not because CDK or Terraform are inherently flawed.

> I would love to see CDK become less buggy though!

I've been using it professionally for over 5 years and have encountered a single bug, which arose due to version mismatches in different libraries (and so was easily resolved). I certainly won't claim that _no_ bugs exist - though, skimming the Issues page, the considerable majority appear to be Feature Requests. Either way, I feel extremely confident claiming that a bug in CDK code is significantly less likely than making a mistake when attempting to reimplement-in-boto3 all the wiring and dependencies of a complex stack.

Hand waving away a more than 10x increase in issues won't make them go away. That's a pretty clear indication things are wrong. CDK/cloudformation is objectively buggy compared to boto3/the standard API. Terraform is unusable for all but the most basic tasks, with issues like not being able to get private IPs for certain resources, and seemingly no plans to support the many inherently procedural operations that one may need to perform on AWS.

> Candidly, to describe CDK/Terraform as "essentially API wrappers" betrays the fact that you didn't really try to use them seriously. Yes, they call AWS APIs under the hood; but if you're only using them as a drop-in replacement for boto3 calls, you are missing out on a lot of the power they provide.

Well I actually reviewed the code as part of my evaluation, and even made the initial version with terraform that I contributed a patch for, so it's an accurate description. CDK is a wrapper for cloudformation...

> Either way, I feel extremely confident claiming that a bug in CDK code is significantly less likely than making a mistake when attempting to reimplement-in-boto3 all the wiring and dependencies of a complex stack.

If you were to actually compare CDK and boto3 examples, you would find they are very close in practice with the major difference being that you _may_ need to diff existing resources before performing updates with boto3. Not hard to do in practice and gives you the opportunity to choose exactly how to handle different scenarios, which I see as a plus. You still need to learn AWS concepts and have a strategy for error handling.

I'm glad CDK it works for your use case! I'm provisioning entire build and runtime environments as a service, and chose the API wrapper that is clearly given first priority at AWS.

> Not hard to do in practice and gives you the opportunity to choose exactly how to handle different scenarios, which I see as a plus. You still need to learn AWS concepts and have a strategy for error handling.

These are certainly fair points.

Thank you for your civility - I re-read my previous comment and am not proud of the tone that I struck.

No worries. I just saw it as being challenged on my opinions, which is a good thing.

I would contest that claim, honestly. If you mean the Terraform AWS provider, that has very good documentation, as do all the Terraform Hashicorp providers, but AWS itself is all over the place. They have way too much. Run into nearly anything I can't figure out and have to go their solutions architect for and I get links to 15 different blogs that aren't even part of the main documentation. Been fighting to figure out how to authenticate a AWS VPN throug Azure AD for weeks, though to be fair there, the defect is mostly on Microsoft's side, not Amazon's. I just spent the entire day today getting rsql to finally work for querying Redshift on a M1 Mac and their documentation seems to just be flat-out wrong. All the paths they think Homebrew installs stuff into are not the right paths. They offer a arm ODBC adapter, but rsql itself only comes in x86 for some reason, so they fail if you try to use them together and you have to get the x86 ODBC instead.

Also, not Amazon's fault, but I consistently get annoyed that when you web search the documentation for awscli, the top links always take you to the awscli v1, not v2.

To be fair again, I don't even know that it's a solvable problem. AWS offers too many services, too many ways to access them, and makes changes too frequently. They can't just unpublish anything because someone out there is still using some combination of each version of server and client side services. But it makes it very hard to find exactly what I'm looking for. Probably made all the worse by some of the subtle differences in GovCloud, but having very little GovCloud-specific documentation.