Live data from Hacker News

The Amazon Builders' Library

aws.amazon.com

41–50 of 52 posts

Re: The Amazon Builders' Library

#41

Disclaimer: ex-AWS Wowzer. Amazon, and in particular AWS, sits on a treasure trove of hard-earned lessons abt designing, building, operating, maintaining systems at scale. I'm glad they have began to share some of that know-how with the external world. I wrote abt longing for AWS to do this some 6 months back [0] as I dearly missed access to those docs and videos that helped me understand so much abt the underpinning…

The Charlie Bell ops review meeting (and the various 'make sure you don't embarrass us in front of Charlie' pre-review meetings) is especially critical. It's not just about having the techniques for doing ops well, it's about leadership prioritizing it through both words and actions.

Re: The Amazon Builders' Library

#42
post #11
post #9

Does anyone know why Amazon engineers always seem to write so well? Any time I read technical content from Amazon, I am struck by how clear and concise it is.

Amazon has a very strong written culture (search for 1 pagers and 6 pagers). To be effective at higher levels in any role you need to be good at it.

One of the authors here. I agree with all the folks’ suggestions here! When I was in college, I took extra writing courses beyond what was required for an engineering degree (they counted toward general humanities credits I think). People always told me how important communication and writing was in engineering. Not sure the courses are what did it for me entirely, but it certainly taught me concise “technical communication”, as well as story telling, and forced me to practice! A huge key to good, clear writing is reviewers. I ended up essentially rewriting some of the articles multiple times based on feedback. And we all had some great editorial help on these articles to give the articles that final polish.

Re: The Amazon Builders' Library

#43
post #11

Earlier quoted context omitted.

Amazon has a very strong written culture (search for 1 pagers and 6 pagers). To be effective at higher levels in any role you need to be good at it.

Any tips on how to get better at this?

Start with the basics. Read a business writing book, articles, or take a course on it. Even a one-hour course will teach you something new. Beyond that, some things that help me address my weak spots:

1. Make sure your first paragraph or executive summary answers the questions: Why does this doc exist? Who is the expected audience? What actions or decisions does the author expect from the audience after reading the doc?

2. Run things through an analyzer like Hemingway[1]. It'll point out obvious things to fix.

3. Do a reverse-thesaurus editing pass. Remove adjectives and flowery language where possible. Challenge yourself to lower the reading level. Even if your audience has PhDs they'll read and comprehend simple language faster.

4. Do an editing pass for missing numbers. Vague language, unsupported assertions, and missing quantities make arguments easy to refute. Look for words like "many", "most", "a lot", "major" "severe" "large" and replace them with hard numbers where possible.

5. Do an editing pass for "So, what?" and remove anything that isn't necessary to support your core argument or purpose. Assume your audience is smart but has very little time. Too much detail will make them start to skim and miss things. Appendixes are your friend here. Leave links to appendixes for readers that have questions or want more detail.

6. Nothing beats a human reviewer. Professional writers have editors too.

[1] http://www.hemingwayapp.com/

Re: The Amazon Builders' Library

#44
post #11

Earlier quoted context omitted.

Amazon has a very strong written culture (search for 1 pagers and 6 pagers). To be effective at higher levels in any role you need to be good at it.

Any tips on how to get better at this?

Write A Lot

When I started at amazon I was encouraged to pitch a project or feature once a month. More importantly I was encourage to write up things I disagreed with or try to sell stuff that was very half assed, and work on getting it to a real idea.

As I did this I got better and better. I can write up 3-5 page design docs in about 1-2 hours now and these can bootstrap others into your thinking very easy. I've found that they also just ground an argument when everyone is arguing about totally different things. Even if they are now all arguing AGAINST your idea, you've made progress.

It's just a muscle you have to exercise. And iterate with feedback. Learn from where people have trouble understanding your document. If they don't understand it, take it as feedback that you are not clear enough.

TLDR Write Write Write

Re: The Amazon Builders' Library

#45

Earlier quoted context omitted.

Any tips on how to get better at this?

Write more and find ways to get feedback on your writing. It's important to get outside input to help you see the things that don't work and experienced readers/editors/friends/coworkers can often provide suggestions on how you can fix it.

Suggestions are great. Whats better is just taking anything that people don't understand as "area for improvement". Then write it and see it it's better. Iterate. You'll learn your own style.

Re: The Amazon Builders' Library

#46
post #9

Does anyone know why Amazon engineers always seem to write so well? Any time I read technical content from Amazon, I am struck by how clear and concise it is.

Writing is, indeed an essential part of Amazon's culture. I also am convinced that the writing culture contributed to the company's success. It's not just PM or SDMs. Engineers at every level are expected to write well. Most meetings often start with reading the time, even up to 30-45 mins. It does work and forces people to think as there is no difference between writing clearly and thinking clearly. I think everyone recognizes that and uses the culture to their advantage. As an SDE, I just love it.

Re: The Amazon Builders' Library

#47
post #13

Earlier quoted context omitted.

Any tips on how to get better at this?

Write more. Read more. Seriously. It just takes practice. https://ceklog.kindel.com/2018/04/24/be-a-great-reader/

Of all the very specific suggestions and recommendations, this really is the best one. There is really simple technique for getting better at anything: do more of it.

I wonder if this is simply because human brains are just create specialized neural pathways for special tasks that occur more frequently. So it takes a lot of effort for someone who has never driven a car to drive but after they learn driving it’s automatic (same for language and any other skill)

Re: The Amazon Builders' Library

#49
Reading this snippet in the article about leader election in distributed systems: "Each item of data still belongs to a single leader, but the whole system contains many leaders.". It could not be a clearer statement of Conway's law[0]. Orgs ship their org chart. The technical architecture at AWS absolutely reflects the org chart and business organisation of Amazon generally.

[0] https://www.techopedia.com/definition/31927/conways-law

Re: The Amazon Builders' Library

#50
I've worked in AWS for five years. I get paid, but the kind of knowledge in these pieces are by far the most valuable thing I've gotten from working there. I've been in it. I've used these principals. I've seen what happens to drive these recommendations first-hand. I've worked to design and build systems that follow and support these guidelines and principals.
Post reply on HN