5 ms·

> Reading Cognito docs feels like someone took three separate manuals, threw them in a blender, and then sprinkled in some outdated Stack Overflow answers for f

> Reading Cognito docs feels like someone took three separate manuals, threw them in a blender, and then sprinkled in some outdated Stack Overflow answers for flavor. This is my experience with basically all of AWS documentation. It is nearly always either (1) far too high-level to be of any actual use, or (2) far too verbose, with a massive volume of superfluous information I need to parse and discard before I get to the stuff I am trying to figure out. As just one example, I recently needed to link an AWS Partner Central account with an AWS Management account, and process and documentation was painfully complicated: https://docs.aws.amazon.com/partner-central/latest/getting-started/account-linking.html https://docs.aws.amazon.com/partner-central/latest/getting-s...

deleted 1mo ago
[deleted]
infecto 1mo ago
That’s my experience with any of the 3 hyperscalers when reading docs. Millions of versions, blog posts and just overall massive challenge to get to the root of it. Funny the one thing I was always able to immediately and quickly digest, AWS Textract because they have a great python library with the kind of documentation I expect from a python project.
- automatic6131 1mo ago
  Documentation clearly following Conway's law: shipping the org chart.
- disgruntledphd2 1mo ago
  > That’s my experience with any of the 3 hyperscalers when reading docs. I used to hate the AWS docs, now I use Azure and I hate that so much more. At least AWS had loads of (bad) docs that you could string together to figure out how to do something. With Azure, there's just no docs (except for bad videos), and they literally tell you (at the top of every page) that you can do this with AI (I know I can do it with AI, but I'd prefer if I could read your docs to make sure the machine isn't doing something dumb). My expectation is that I'll end up on GCP in a few years, and that will be bad in hilariously different ways.
  - abofh 1mo ago
    Yes, gcp has volumes of available accurate documentation, but it's almost entirely incomprehensible and bizarrely undiscoverable by search
    - ferngodfather 1mo ago
      If only they had a parent company that specialised in search
  - alasdair_ 1mo ago
    GCP is famous for having two ways to do everything: the undocumented way and the deprecated way. You choose.
    - disgruntledphd2 1mo ago
      I've been making this joke about Google (big tech in general) for years. There are two ways to do everything; one is deprecated and the other is not yet feature complete. Glad to know that they're allowing their customers a taste of what it's like to work at Google.
      - vrosas 1mo ago
        I feel like I'm the only person on HN that doesn't have any major (or cliche) problems with GCP, even after using it for a decade at this point. Like it's not perfect and I've hit weird roadblocks along the way but I've dabbled AWS and I currently use Azure at work and those are hilariously bad in their own ways, people just seem to kind of be used to it?
        deleted 1mo ago
        [deleted]
        antonvs 1mo ago
        I like GCP as well, having previously used AWS for many years. The biggest issue is that it's taken Google a long time to figure out what enterprise security is - it's not something what was in their DNA - and the product shows it. They're too focused on weird fancy half-assed "beyond" solutions to properly implement the basics. They dangle clever federated etc. solutions that only work in some circumstances so that you're better off just avoiding them, but the more basic alternatives are limited in their own way because they focus too much on the fancier solutions.
- mlinhares 1mo ago
  No one gets promoted for writing good docs.
  - Spooky23 1mo ago
    They get promoted for fucking with them. We were in the middle of a big fight with Microsoft support over a product defect. They literally updated the product docs in realtime and revised the sizing guidance for the product to be about 5% under our sizing. It was too specific a number to be a coincidence. We were at war with them, so the team was capturing the documentation and timestamping it. They gaslit us to run the clock so the product would slide outside of mainstream support.
- mixedbit 1mo ago
  My experience with Boto: need some S3 manipulation logic, here is an official documentation that shows how to solve the exact problem with Boto, one caveat, this version of Boto is deprecated. Do the same with the newest version? Not possible.
- sandeepkd 1mo ago
  I do not really want to defend any of the companies here but the reality is that documentation is always a thankless job. People do it to get their project out there, get limelight and move on. There is not much incentive for the teams to manage the documentation actively unless the its a business priority. I am myself in the IDP business, was trying to understand the pain points of the user. Even though I am not big fan of AWS but I find that the concerns are baked into the hope that using an IDP would some how make is very easy > Flexibility of doing local development while on plane Really depends what you are expecting from the IDP but personally this is one off situation and in most cases its not worth solving. We are in such a interconnected or dependent state where local development without internet is really hard. > Configuration issue The features of a solution are two edged sword, it provides people options to tailor it for their own use case and yet at the same time it adds to the learning curve. Good default might have been useful here, however it looks like Author only wanted email and nothing else so it was a departure from defaults > UI customization A lot of providers allow some flexibility with the UI but not a whole lot. And then some allow you to host on your website and call the API's for the authentication flows using SDK. Personally this one is tricky, its a UX vs security topic. As a thumb rule never trust the client. The request headers and ability to interact with browsers are what provides you with relatively better state and session control. As an IDP provider I do not want to loose that and still be on the hook for security.
  - swyx 1mo ago
    > As a thumb rule never trust the client. The request headers and ability to interact with browsers are what provides you with relatively better state and session control. As an IDP provider I do not want to loose that and still be on the hook for security. ok so why NOT allow extreme ui customization since client is untrusted anyway? i dont get it. theres no security concern (within this ui) bc the whole thing is untrusted.
ryanchants 1mo ago
I always say that AWS docs are exhaustive, but exhausting. Mostly because they're spread across half a dozen places. The answer you need is normally in there somewhere, but good luck finding it. And when I remember the docs contain some fact I want re-reference, I can never find it again.
- colechristensen 1mo ago
  Most of my interactions with AWS docs end up being pretty useless, as in they are information-free. Like describing how to fill out a form and press next in a wizard which boil down to "fill out the Name field with a name and press next" and every once in a while there will be a tiny amount of information but most of it is useless and usually the information you're looking for isn't there. Nobody using AWS needs to be told "in order to add a hoozit, press the add hoozit button, fill out field A then fill out field B then fill out field C and then press next" Now there's an interesting idea, have an LLM crawl their entire docs and cull everything obvious or content free and compile what's left
- raffraffraff 1mo ago
  I recently implemented CloudFront signed urls for accessing S3, where my app uses KMS keys to sign the url. Sounds simple and obvious but for the entire history of Cloudfront and KMS it was not! It is not documented to work, nor could I find any explicit AWS documentation saying that it wouldn't work either. And there's a just bunch of anecdotal reports (blogs, github issues) that it doesn't work. But very recently (April I think) Cloudfront and KMS, for the first time ever, both started to support the same key algo/size. So it's now possible, but I stumbled on it, and have never seen a recipe for using them together. So AI doesn't know about it either! I was finally able to stop managing and rotating TLS key pairs, replicating private keys globally to my apps. So: who really reads those little boring announcements, and connects the dots? Seemingly, not even AWS themselves!
sznio 1mo ago
>It is nearly always either (1) far too high-level to be of any actual use, or (2) far too verbose, with a massive volume of superfluous information I need to parse and discard before I get to the stuff I am trying to figure out. I guess that's what they trained Opus 5 on
sorentwo 1mo ago
Had to go through the exact same process of linking Partner Central with Marketplace. The console suggested following multiple video tutorials and linked to docs that may be outdated. They have this AI tool on every page that links to the same content or references settings panes without linking anything.
vel0city 1mo ago
I love it when I read some AWS docs to get a feel for what to do, start to build things, find something that seems like it should just work, then do a lot of digging to figure out what I'm doing wrong, only to find a slightly different page of pretty much the same documentation stating whatever I was wanting to do just isn't supported and can't be done, and I've just wasted a day or two trying. Fun times.
unixhero 1mo ago
I reckon the documentation was fine. Together with AWS reinvent videos and together with well architected. Except for IAM that was a huuuge struggle. Sadly no companies at all are qilling to use anything else than Azure nowadays.
DanielHB 1mo ago
when LLMs first became popular my first real use for them was to find information about AWS services. LLMs have read it all and can (mostly) synthesize what you ask if it is in the docs.
grackasthebig 1mo ago
They’re gaming search for attention. Being useful to a human is incidental side effect.

deleted 1mo ago

[deleted]

infecto 1mo ago

That’s my experience with any of the 3 hyperscalers when reading docs. Millions of versions, blog posts and just overall massive challenge to get to the root of it. Funny the one thing I was always able to immediately and quickly digest, AWS Textract because they have a great python library with the kind of documentation I expect from a python project.

automatic6131 1mo ago
Documentation clearly following Conway's law: shipping the org chart.
disgruntledphd2 1mo ago
> That’s my experience with any of the 3 hyperscalers when reading docs. I used to hate the AWS docs, now I use Azure and I hate that so much more. At least AWS had loads of (bad) docs that you could string together to figure out how to do something. With Azure, there's just no docs (except for bad videos), and they literally tell you (at the top of every page) that you can do this with AI (I know I can do it with AI, but I'd prefer if I could read your docs to make sure the machine isn't doing something dumb). My expectation is that I'll end up on GCP in a few years, and that will be bad in hilariously different ways.
- abofh 1mo ago
  Yes, gcp has volumes of available accurate documentation, but it's almost entirely incomprehensible and bizarrely undiscoverable by search
  - ferngodfather 1mo ago
    If only they had a parent company that specialised in search
- alasdair_ 1mo ago
  GCP is famous for having two ways to do everything: the undocumented way and the deprecated way. You choose.
  - disgruntledphd2 1mo ago
    I've been making this joke about Google (big tech in general) for years. There are two ways to do everything; one is deprecated and the other is not yet feature complete. Glad to know that they're allowing their customers a taste of what it's like to work at Google.
    - vrosas 1mo ago
      I feel like I'm the only person on HN that doesn't have any major (or cliche) problems with GCP, even after using it for a decade at this point. Like it's not perfect and I've hit weird roadblocks along the way but I've dabbled AWS and I currently use Azure at work and those are hilariously bad in their own ways, people just seem to kind of be used to it?
      - deleted 1mo ago
        [deleted]
      - antonvs 1mo ago
        I like GCP as well, having previously used AWS for many years. The biggest issue is that it's taken Google a long time to figure out what enterprise security is - it's not something what was in their DNA - and the product shows it. They're too focused on weird fancy half-assed "beyond" solutions to properly implement the basics. They dangle clever federated etc. solutions that only work in some circumstances so that you're better off just avoiding them, but the more basic alternatives are limited in their own way because they focus too much on the fancier solutions.
mlinhares 1mo ago
No one gets promoted for writing good docs.
- Spooky23 1mo ago
  They get promoted for fucking with them. We were in the middle of a big fight with Microsoft support over a product defect. They literally updated the product docs in realtime and revised the sizing guidance for the product to be about 5% under our sizing. It was too specific a number to be a coincidence. We were at war with them, so the team was capturing the documentation and timestamping it. They gaslit us to run the clock so the product would slide outside of mainstream support.
mixedbit 1mo ago
My experience with Boto: need some S3 manipulation logic, here is an official documentation that shows how to solve the exact problem with Boto, one caveat, this version of Boto is deprecated. Do the same with the newest version? Not possible.
sandeepkd 1mo ago
I do not really want to defend any of the companies here but the reality is that documentation is always a thankless job. People do it to get their project out there, get limelight and move on. There is not much incentive for the teams to manage the documentation actively unless the its a business priority. I am myself in the IDP business, was trying to understand the pain points of the user. Even though I am not big fan of AWS but I find that the concerns are baked into the hope that using an IDP would some how make is very easy > Flexibility of doing local development while on plane Really depends what you are expecting from the IDP but personally this is one off situation and in most cases its not worth solving. We are in such a interconnected or dependent state where local development without internet is really hard. > Configuration issue The features of a solution are two edged sword, it provides people options to tailor it for their own use case and yet at the same time it adds to the learning curve. Good default might have been useful here, however it looks like Author only wanted email and nothing else so it was a departure from defaults > UI customization A lot of providers allow some flexibility with the UI but not a whole lot. And then some allow you to host on your website and call the API's for the authentication flows using SDK. Personally this one is tricky, its a UX vs security topic. As a thumb rule never trust the client. The request headers and ability to interact with browsers are what provides you with relatively better state and session control. As an IDP provider I do not want to loose that and still be on the hook for security.
- swyx 1mo ago
  > As a thumb rule never trust the client. The request headers and ability to interact with browsers are what provides you with relatively better state and session control. As an IDP provider I do not want to loose that and still be on the hook for security. ok so why NOT allow extreme ui customization since client is untrusted anyway? i dont get it. theres no security concern (within this ui) bc the whole thing is untrusted.

ryanchants 1mo ago

I always say that AWS docs are exhaustive, but exhausting. Mostly because they're spread across half a dozen places. The answer you need is normally in there somewhere, but good luck finding it. And when I remember the docs contain some fact I want re-reference, I can never find it again.

colechristensen 1mo ago
Most of my interactions with AWS docs end up being pretty useless, as in they are information-free. Like describing how to fill out a form and press next in a wizard which boil down to "fill out the Name field with a name and press next" and every once in a while there will be a tiny amount of information but most of it is useless and usually the information you're looking for isn't there. Nobody using AWS needs to be told "in order to add a hoozit, press the add hoozit button, fill out field A then fill out field B then fill out field C and then press next" Now there's an interesting idea, have an LLM crawl their entire docs and cull everything obvious or content free and compile what's left
raffraffraff 1mo ago
I recently implemented CloudFront signed urls for accessing S3, where my app uses KMS keys to sign the url. Sounds simple and obvious but for the entire history of Cloudfront and KMS it was not! It is not documented to work, nor could I find any explicit AWS documentation saying that it wouldn't work either. And there's a just bunch of anecdotal reports (blogs, github issues) that it doesn't work. But very recently (April I think) Cloudfront and KMS, for the first time ever, both started to support the same key algo/size. So it's now possible, but I stumbled on it, and have never seen a recipe for using them together. So AI doesn't know about it either! I was finally able to stop managing and rotating TLS key pairs, replicating private keys globally to my apps. So: who really reads those little boring announcements, and connects the dots? Seemingly, not even AWS themselves!

sznio 1mo ago

>It is nearly always either (1) far too high-level to be of any actual use, or (2) far too verbose, with a massive volume of superfluous information I need to parse and discard before I get to the stuff I am trying to figure out. I guess that's what they trained Opus 5 on

sorentwo 1mo ago

Had to go through the exact same process of linking Partner Central with Marketplace. The console suggested following multiple video tutorials and linked to docs that may be outdated. They have this AI tool on every page that links to the same content or references settings panes without linking anything.

vel0city 1mo ago

I love it when I read some AWS docs to get a feel for what to do, start to build things, find something that seems like it should just work, then do a lot of digging to figure out what I'm doing wrong, only to find a slightly different page of pretty much the same documentation stating whatever I was wanting to do just isn't supported and can't be done, and I've just wasted a day or two trying. Fun times.

unixhero 1mo ago

I reckon the documentation was fine. Together with AWS reinvent videos and together with well architected. Except for IAM that was a huuuge struggle. Sadly no companies at all are qilling to use anything else than Azure nowadays.

DanielHB 1mo ago

when LLMs first became popular my first real use for them was to find information about AWS services. LLMs have read it all and can (mostly) synthesize what you ask if it is in the docs.

grackasthebig 1mo ago

They’re gaming search for attention. Being useful to a human is incidental side effect.