
Why is AWS documentation so poor? - aws_simplified
So I&#x27;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.<p>I decided to do something about this and dedicate a youtube channel to give detailed walkthroughs using AWS technologies. I&#x27;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.<p>I started this channel of with two videos:<p>1) SNS to Lambda Trigger walkthrough - https:&#x2F;&#x2F;youtu.be&#x2F;PsJsP-7cydk<p>2) SQS to Lambda Trigger walkthrough - https:&#x2F;&#x2F;youtu.be&#x2F;JJQrVBRzlPg<p>I&#x27;m going to be posting new videos fairly regularly. I&#x27;m open to feedback, comments, or suggested topics. Any support is appreciated.<p>Thanks
======
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.

------
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/](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.

------
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?

------
ta010101
Documentation is one of the few "open" area of amazon:
[https://github.com/awsdocs](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,...

~~~
ta010101
Also, a LOT a video material
[https://www.youtube.com/user/AmazonWebServices/](https://www.youtube.com/user/AmazonWebServices/)

Difficulty is probably to find the good ones.

~~~
verdverm
AWS also seems to have good SEO on their docs, so it becomes hard to search
for answers from other sources.

------
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.

