Dear AWS: I Love Your Products But…

…Your Approach To Documentation Is Hurting You And Your Customers

Image by Midjourney

Dear AWS: I love your products. You kick-started the entire cloud-platform industry; you set the bar for it, and you continue to raise the bar. Your products are powerful, your prices are the fairest in all the land.

You truly value your customers, and it shows.

BUT.

You fall short — you’ve always fallen short — on documentation. On making it possible and attractive for naive users to dip their toes in and set them on their path to becoming the AWS heroes that you truly deserve.

Background

I served in the military for six years, and one of the lessons I learned most keenly is to avoid knowledge siloing and to make myself as replaceable as possible by providing comments and documentation to help the next person along. There will always be more challenges, there will always be more problems to solve, and not making existing solutions easy to work with for others — and ourselves — will always come back to bite us in the end.

Context matters. Give the average developer a few weeks of working on a new project and they’ll have forgotten a lot of the details of what they were doing in the old one.