HN Explorer

Why is AWS documentation so poor?

30 points by aws_simplified ↗ HN
So I've been using AWS technologies every day over the past 4 years. I find there is a consistent pattern with AWS documentation, its filled with detail but hard to sift through it all to find the details that actually matter. Speaking to my coworkers, it seems everyone has the same feeling.

I decided to do something about this and dedicate a youtube channel to give detailed walkthroughs using AWS technologies. I'm making a special effort to focus on the numerous options that are presented and explain what they mean, while giving special emphasis to the settings you should probably pay attention to.

I started this channel of with two videos:

1) SNS to Lambda Trigger walkthrough - https://youtu.be/PsJsP-7cydk

2) SQS to Lambda Trigger walkthrough - https://youtu.be/JJQrVBRzlPg

I'm going to be posting new videos fairly regularly. I'm open to feedback, comments, or suggested topics. Any support is appreciated.

Thanks

14 comments

[ 3.2 ms ] story [ 18.6 ms ] thread
bradknowles
Everything at Amazon and AWS is done by two-pizza teams. Everything.

Each team is expected to be largely self-supporting.

That includes UI, documentation, everything.

They can leverage the work of other teams, if they choose.

Once the product has been created, it is then up to them to get the word out about their product in order to get other teams to use it.

So, there is a huge discoverability problem in just finding out what tools exist and what they do.

And each team is largely responsible for policing themselves on compliance with standards, or figuring out what best practices are and then adhering to them.

So, how many employees does Amazon and AWS have? How many two-pizza teams can you create from those numbers?

How many two-pizza teams would you have to have before you start having duplication of effort — or schizophrenic implementation of differing interpretations of standards?

neuroticfish
> two-pizza

What does this mean? The size of a team that 2 pizzas can feed?

sethammons
yup, exactly. Which can vary wildly. I used to eat a pizza by myself, and now I limit myself to two slices. And a guy on my team does not like pizza. I find it better to just say 5-9 members.
ai_ia
>How many two-pizza teams would you have to have before you start having duplication of effort — or schizophrenic implementation of differing interpretations of standards?

Steve Yegge wrote a rant on Amazon[1] which paints a different picture of Amazon documentation culture inside the company.

Even though they have a large number of teams, they seem to have well defined standard for API Documentation as far as my understanding.

[1] https://gist.github.com/chitchcock/1281611

mooreds
I dunno. AWS documentation covers complicated systems. Sometimes that means that the docs are complicated. I have found them to be thorough. Only issue I have is that search is awful, but using Google fixes that.

If you want high level docs, have you looked at the well architected framework?

https://aws.amazon.com/architecture/well-architected/

I guess I am missing something. Can you point me to some docs that are done well (in your opinion)?

darkcha0s
Having worked with both, Azure’s documentation tends to be very well maintained.
nirse
Also working with both, I often find that Azure's docs mainly focus on basic tasks and leave out the more advanced, which makes them good but incomplete. AWS, on the other hand, I have found to be more complete, documenting more features of the platform, but they are not always as clear as Azure's.
verdverm
Google Cloud docs are far superior, as is the overall UX/DX.
ta010101
Documentation is one of the few "open" area of amazon: https://github.com/awsdocs

Since it is their job, probably technical writers fix documentation tickets? Which documentation specifically are you refering to as "poor"?

Videos are a useful complement (thanks!) to documentation, but may not be enough to replace it, especially as reference (for details).

Different users need different documentations: tutorial, reference, specifications, architecture,...

oliyoung
or, why should we, who pay AWS thousands per month, help write the documentation for their commercial product?
pbecotte
The AWS docs annoy me SO MUCH. As others have noted, there is a LOT of them, and they cover every feature. But I cant think of any of them that explain how stuff works. There will be three different versions explaining how to set some option with cli, sdk, and console versions...but they never explain what that option actually does. The examples are always at the tutorial level (there are so many * in IAM permissions in their docs). For something that is so very much a professional product where the details are important, their docs should really have the more in depth details. Like what are the tradeoffs with Aurora? How exactly do the load balancers handle connections and scaling? What does the "certificate" option in codebuild do?
aketchum
My cynical opinion is that companies have little incentive to fix their documentation because if the documentation is poor the client is more likely to pay for a consultant from the company for support, or for a higher support tier.