Hacker News Reader

Comment by cateblanchett | Hacker News Reader

doesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.

View on HN

Amazon is high documentation, high meetings culture. The documentation is reviewed by peers, bar raisers, and leaders in a process called document read before being official.

Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within your sub team or the follow up meetings from doc reads or the new team launch meetings, etc. Amazon tech is a high meeting culture.

so the worst of both worlds

Why? I think this sounds great.

If you are writing for reviews, you are not writing for your peers. The question is: who will be using the documents?

Read an amazon 6 pager... then try to write one, about anything. and then invite all of your co-workers to pick apart every single line of your document.

Correct. Be careful about sharing a document in progress, notes, or just simple thoughts in text. People will pick it apart word by word. Why? It is the culture Amazon created. Sometimes it helps. Sometimes it's a waste of everyone's time.

Sure, but oftentimes technical documentation is severely lacking. PRFAQs, initial design docs, etc. are thoughtfully created and thoroughly reviewed, but the actual implementation lacks the documentation required to make onboarding (be it new team members or new dependent teams) as smooth as it could be. My favorite is finding an out of date Wiki page from 6 years ago that contains a partial list of API method names, descriptions if you're lucky, and then nothing else, not even a link to the service's AAA page/etc. or a high-level summary of what the service _does_ or _why_. With how many moving parts there are and how inaccessible non-platform-level documentation is, the new hire experience at Amazon can be rather daunting. Even SDE1/2s that are a year in often have a very incomplete picture of what's going on in their own domain space. Too much tribal knowledge.

this statement needs some detail, "high meetings" is obscuring that meetings use the docs (not meetings with no agenda or lots of presentations). meeying use docs as the primary driver, be that a narrative or analysis of a dataset

As someone who has to use Amazon's external documentation: it's absolutely terrible. Worst docs of any company we have to interact with at the API level.

They need high documentation to support their employee churn.

> feel free to chime in

Pun intended?

Reply on news.ycombinator.com