About: ¡Hola! 📄 I'm Alejandra, primary owner for OSS Dev Docs & Education of AsyncAPI initiative at Postman. 👩🏻💻 I founded @sheCodesNow. 🦮 Canela is my Service Dog, I'm autistic 🧠. 🇲🇽 Hecha en México.
Dear early adaptors to Cloud and AWS,
What AWS service are you struggling to learn? What’s painful? What’s blocking you from doing what you want to do?
Has our documentation helped? What’s lacking?
👉🏽 Send me doc links and/or detailed specifics of what you need. I'm listening.💜
~Alejandra💁🏻♀️ y Canela🐾
Really? The docs are pretty good in IMO and the UI, while not great is good enough for most services. TBH I don’t use the UI much these days though.
I spent many years using Oracle products - now that is poor docs and UI!
I hear you that the UI and the docs should be held to a higher standard. I will pass this feedback to my team as well. (I am making a list of answers I receive online.)
Do you have more specific doc sections you want to point out that you found the most confusing?
I find the documentation, guides, and mental model pretty straightforward for most AWS services...
I tend to find things break down around permissions, groups, and how certain things plug together. That's inherently more complex in general but definitely where I struggle the most. I suspect any major cloud infrastructure provider's major opportunity for growth is the "how things plug together" piece of things anyway.
I SO agree with you, and I was actually just mentioning this to a colleague last week!
Do you have a specific group offering or service from AWS that you found the most confusing to "plug together" ? What do you think we should have done better?
App Mesh and Event Bridge seem like great examples of this, but don't solve the real challenge... IAM. Maybe the most interesting thing I've seen in that space is cloud recorder. A chrome extension that watches you take actions in the dashboard and outputs Terraform, limited IAM JSON, er cetera... Why doesn't AWS just have this themselves???
For beginners it's not intuitive at all compared to Firebase. I am more inclined to start my side/small projects with Firebase always.
Amazon Cognito!
All the documentation is there but the way it is organized, important information is hidden in subsections and there are few practical examples.
I have pieced together my own integration into my monolith but it was trial and error.
I would like to add that while documentation is not an issue, sometimes what I wish itd come with are recommended values for certain properties and when does it make sense to increase and decrease it and what are the pros and cons of that.
One example being ReservedCpncurency setting on LAMBDA or VisibilityTimeout value on SQS.
Documentation would tell you that it takes an integer or a String and what it does. However, when you are developing a production level app, end user has no idea what he/she should set those values to.
I only found out about it after running into some article only. For instance, how they recommend that VisibilityTimeout setting for SQS should be set to 5 times the value of a LAMBDA function timeout value.
Itd be good to have a central repository somewhere where one can find this sort of best practices.
The DevOps tools (CodeDeploy and CodePipeline) are a pain to work with. No proper documentation and very bad logs.
I have received this feedback on Twitter where I made this same post. Thank you for your feedback, you're not alone! We have much to improve.
I've not been able to find a solution to a very simple thing...
A Static website hosted with S3 + cloudfront that 301 redirects to both HTTPS and to a WWW subdomain.
I've been able to redirect to one or the other, but not both.
DynamoDB. It has some of the worst documentation that I've ever seen. Implementation as well is mind bogglingly complex.
Check out dynamodbbook.com (no association, just fan) - goes through so much of how/why to use dynamodb - it's a VERY different mindset than typical relational databases, and I agree the aws documentation is factual, just not functional.
Thanks for the suggestion!
In my opinion, it's best to not expect ANYTHING out of DynamoDB and start with a basic assumption that it is a key-value store. Then, you can build from there.
I'm saying this because almost every feature that I assumed worked in one way, turned out to work in another. Plus, there are so many features behaving differently in different scenarios, which, if you want to find that out, you have to go through 3 different documentation pages or blog posts.
We have an amazing DA that is currently working on improving the DynamoDB docs. He agrees with you, trust me! Thank you for this feedback, I will be passing this on to him.
Most services are ok in isolation but it’s when you start tying them all together It gets complicated really fast!
TBH, I've found some of your non-documentation help is really good. Some of the case study architecture solutions videos that have been put up I've found really useful.
So, first thing: please add support for .net core on Linux for Elastic Beanstalk. I really like being able to manage most of my application through Elastic Beanstalk and get load balancers setup the way I want, though I don't like for .Net Core always having to use Windows. Sure I can go and setup everything from scratch, but it would be nice to see that I can use it also, since you support it on Windows.
The next thing is just the whole UX/UI. It feels disconnected. The feel/flow of the UI for one service doesn't at all flow the same way for different UI's.
Example: sometimes the steppers for some resources support the back button. You can click and it takes you back to previous step. Then there are times where the steppers or even different tabs do not support the back button. Click the back button and it just flat out EXITS you to a completely different UI. No warning at all. That's the thing that really frustrates me the most.
I understand that it is impossible for a platform as large as AWS to have a consistent UI all the time for services, as things change and you can't change them all at once. Though the biggest thing I ask for, is if one UI supports the back button then the rest of your UIs should also.
Thank you for explaining in such detail what you think would make it a better experience for you! I will be passing this on to the Elastic Beanstalk team.
Hope you noticed the release of .NET Core Linux support that came out this week. aws.amazon.com/blogs/developer/aws...
I actually did not. I must have missed that announcement. Thanks for bringing it up! I'll definitely have to check this out soon!
Creating a Cloudformation for an Api Gateway, for me the documentation for it is so separated into topics that I found myself going back and forth and having no idea on how to organize them in the file and which one comes first and which one should be inside of what
Most of the individual service documentation is great. I love the docs for boto3!
Where I find problems is when I have an issue involving several different products. An example from the past few days, I've been struggling to successfully attach a SSL certificate to a domain linked to an EC2 instance.
There's a lot of documentation around components of this, but I haven't figured out how to stitch all the components together (EC2, Certificate Manager, Route 53) to get over the last hurdle so that I can use HTTPS to access the domain using the existing documentation.
If I am new to AWS, going through documentation confuses me more. There needs to be documentation trail that explains how to host through VPS or say how to deploy when on windows etc.
The dev-targeted tooling is useful and I'm always finding something new and delightful (came across SAM last week), but everything about the AWS management console is incredibly cumbersome. Had to find a stack overflow answer on how to view my existing services the other day. I think if your core, day-to-day resources are all-in on AWS it is more learnable, but for the average web developer the console is very overwhelming. I suspect the rationale is that companies will use so many of the services that showing which are "in-use" is noisy, but it almost feels like a dark pattern intended to hide usage and costs.
I'd note that this isn't a problem unique to AWS. Azure has the same issues, and Google to some extent (though Google appears to be getting better at it).
Hard agree on being able to see components in a single view. You can do some things through tag manager etc, but it's not very enjoyable. Seems like a relatively straight forward to comprehend feature.
I have a plan to learn AWS, In Comments users say documentations hard to follow. So Where should I Start ? Is there any Free Course ?
Getting started on the cloud and AWS can absolutely feel confusing! It is a lot to learn and you are not alone.
I have started a youtube channel to help start teaching this from the very beginning. Want to take a look and see if this helps?
Well this blew up.
I am not responding individually ATM since that will take a few days, but I am absolutely reading each and every comment. The plan is to compile the feedback that is repeated the most, and then pass it on to said teams.
I'm still listening, keep telling me how we can make it better. 💜
IAM issues is a common issue being bubbled up to me. Thank you for this detailed feedback!
Overall the UI and Docs are awful. I have seen some many people complaining about this on twitter and I still don't see any changes to make the ui and docs better.