Comment by trallnag
Comment by trallnag 4 days ago
When you talk about docs at AWS, do you mean internal documentation or the public one?
Comment by trallnag 4 days ago
When you talk about docs at AWS, do you mean internal documentation or the public one?
That's an extremely sensible idea in multiple dimensions. It prioritises clarity of thought over rambling discussion in conference calls. I wonder if there's a feasible path to gradually steer an existing organisational structure in that direction.
> if there's a feasible path to gradually steer an existing organisational structure in that direction
The path I took was to just start doing it and expecting it for critical topics within my team (which was around 200-250 people when I started it). It takes several iterations to get good at it and the first few feel like it’s quite foreign and even wasteful. (It puts a lot more work on the author, by design.)
Eventually, it escaped just my group and (with support from others, including the CEO, who liked the process after seeing some of the documents that I or others shared with them) and is now fairly common in the corporate center for our standardized processes, though not nearly as standardized as I perceive Amazon to be in its use.
Basically: start doing it and stick to it for at least 5 complete cycles. Make sure that influential people (not necessarily org leaders) are public in their praise of well-constructed and effective documents.
From experience, yes / kind of; for the project I'm on right now, I introduced ADRs (https://adr.github.io/madr/) as a not-too-formal, but still formal way to talk about technology. This was after ten years of working in more hype-driven culture, where the choice was made by one person, or it was the tech du jour, or some guy spent a weekend playing with it so obviously we should integrate it.
It's a simple shift where people have to do their homework instead of just yeet something over the fence. You want to solve X? Present us with three options and we'll talk about it. You want to introduce Y? But we already use X to solve that, present us with new insights and the justification to spend the time on it.
It's far from perfect and it requires buy-in and (self) discipline, but it's still better than what happened before. Because some companies are still paying the debt of hype-driven development even though the people that introduced it are long gone.
It also means
- You can't take calls from cars
- People leave 2 bullshit comments like "justification needed" for participation points and then go drink coffee instead of actually reading the doc or googling for said justification
- People waste inordinate amounts of time writing docs for things that could be discussed in 10 minutes
Not taking calls from a car sounds like a feature. We don't need more distracted drivers or meeting participants.
> People waste inordinate amounts of time writing docs for things that could be discussed in 10 minutes
I’m very much a writing kind of person when it comes to organizing my thoughts and I worked at a place where we did a ton of written documentation kind of like this. Then I left there and worked remote with a different company whose CEO, when I sent him an email, would pick up the phone and call me. We would then have the 10 minute conversation you’re talking about here. I came to love it because it’s true, a short focused conversation can be a huge timesaver. Since then, I’m often really frustrated by vendors and partners who steadfastly refuse to get on a call, when it’s very obvious to me that a quick call would be a far better use of time than endlessly going back and forth on email.
> - People waste inordinate amounts of time writing docs for things that could be discussed in 10 minutes
What about if someone wants to know what was discussed? You end up telling and retelling the same thing over and over again to get people in the loop, vs pointing to the doc and its remarks. (Depends on the subject of course)
Technical things (algorithms, locations of docker images, code, data, checkpoints, things that were tried but failed) should be documented.
Unfortunately most of the doc culture is people trying to convince each other within the same team that we need XYZ even when everyone with half a brain already knows it. Like "we need more GPUs to get shit done" should be a 10 minute call, not a PRFAQ.
I was in a meeting with an AWS engineer who took it from their car. It felt weird to me.
This is Bezos talking about this: https://youtu.be/e47wAgIhZ7o?si=LKZxoabqrCSCQ1ki&t=64
^ exactly, thanks for taking the answer perfectly.
It's basically panel 2 from this:
Beyond the initial publication of the doc, the peer review process is much more sane than trying to review a bunch of power point slides. Similarly, it's much much easier to refer to a well written document when it comes time to implement or reevaluate an idea than going over some power point slides and maybe an associated recording, to say nothing about searchability, discoverability, and maintainability of an actual written document vs PowerPoint slides.
Also, idle side speculation: I wonder how much (if any) one of the underappreciated early employees @ Amazon had a hand in proselytizing this, given she (MacKenzie) is an author.
Oof, must suck to work for a company who doesn't use technical design docs well. I quite like Oxide's RFD model, based off Joyent's I assume, given who their CTO is. https://rfd.shared.oxide.computer/rfd/1
In my experience these documents were actually never good. I’ve never seen anyone ask for estimates either. Surely it’s better than some other companies but if it were good they wouldn’t need this absolutely horrific oncall
I believe most tech focused companies do it and it's called design docs / RFCs.
Neither, they're talking about the culture of writing documents as a form of sharing ideas. Where other companies might use powerpoint presentations or unstructured meetings to brainstorm on ideas, Amazon instead encourages people to write a document summarizing their thoughts, and then there is a meeting where people silently read and comment on the document, and then afterwards discuss it.