7 ms·

> So when Bezos—in a possibly apocryphally, 128-word memo—wrote that “All teams will henceforth expose their data and functionality through service interfaces,”

by _gabe_ 4y ago

> So when Bezos—in a possibly apocryphally, 128-word memo—wrote that “All teams will henceforth expose their data and functionality through service interfaces,” it was a focused idea that led to Amazon building web services for which it’d be it’s own best customer, and turned AWS into the cloud computing juggernaut it is today. Last I checked, almost every AWS api has a V2. And wait, I just checked, AWS CDK is on V2.28.0. I wonder why the last 28 versions of V2 didn't work if they wrote the documentation first? Last I checked, Mac OS is on like version 11 or something? I'm not a Mac user so I don't follow this stuff. Clearly, documentation is not a silver bullet. If it was, we wouldn't have to continue to rewrite and bump the versions of all of our tools. When I worked at Amazon, writing that 6 page document was like agonizing torture. They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that?? I don't know what other APIs I may or may not have to call to actually get this to work. Implementation details matter a lot. I don't remember who said this, but there's a saying that's something like ideas are worth nothing. Execution is worth everything. And the same thing goes for documentation, what good is documentation without a final product? It's useless.

sumy23 4y ago
> They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that? Isn’t that part of the job? When writing a technical document, you need to research things like dependencies, data storage, caching and estimate expected latency.
- _gabe_ 4y ago
  The only way to get an accurate estimate of expected latency is to measure it in all sorts of different scenarios. You can't measure something that doesn't exist. And relying on other peoples documentation for accurate latency estimates is asking for trouble. The one thing I've learned through profiling a lot of my code is that my intuitions about how long something will take are always wrong.
  - sumy23 4y ago
    Maybe? As an experienced engineer, you should be able to use your experience to estimate the latency. Very few things are truly novel.
    - _gabe_ 4y ago
      As an experienced engineer, you should know that you can never give a good estimate. Very few things are as you would expect them to be. I looked for an article on how to estimate latency. When I Google "how to estimate the latency of my program" the top results are: "Network Latency Guide: How to Check, Test, & Reduce" "How to Measure Latency - Obkio" "How to measure network latency: the 5 best tools - Kadiska" They're all about measuring latency. Honestly I can't find any blog or guide that talks about how to give good estimates. Every time I Google a different variation of this question, it only gives me results that talk about how to measure latency. If you can point me to a good source that talks about how you can provide a good estimate of latency, I would be very surprised ;)
      - pclmulqdq 4y ago
        Use a table of common latencies, add up what's going to happen on your critical path, and multiply by 2. That will be close to your median latency. Edit - when people ask for estimates, they usually aren't asking if it's 1 millisecond or 2 milliseconds. They're asking if it's closer to 1 millisecond or 100 milliseconds.
  - pclmulqdq 4y ago
    Part of your job is understanding what is reasonable to expect from your code and understanding how to estimate things. An estimate that is wrong by a factor of 10 can still be very useful. When you get into the weeds on perperformance, a lot of things get very un-intuitive, but from a high level, it is often not hard to estimate median performance figures for a system within a factor of 10.
noobker 4y ago
> what good is documentation without a final product? Reference material for the features and techniques the product had/was going to have. I've earned years of my salary at a time by referencing documentation for vaporware -- things that never quite made it but that had worked out a ton of problems and documented them along the way.
contingencies 4y ago
This question is well discussed. A lot of the problems that exist in software, a lot of the problems that one encounters in writing... in building a system, in writing a program: those are problems that are caused by not thinking about what you are doing before starting to code. - Leslie Lamport An idiot with a plan can beat a genius without a plan. - Warren Buffett No battle was ever won according to plan, but no battle was ever won without one. - Dwight D. Eisenhower To think, you have to write. If you're thinking without writing, you only think you're thinking. - Leslie Lamport Anything you do is an iterative process. You start out by thinking about something, and then you start writing it, and in the course of writing it, you rewrite and you rewrite and you rewrite. - Leslie Lamport ... via https://github.com/globalcitizen/taoup https://github.com/globalcitizen/taoup PS. Full disclosure: I spent today rewriting something I coded yesterday... but generated a lot of written pages before starting both days! (It's a nontrivial problem. I do planning on paper because it's faster.) Now it's mostly there and well documented.
- _gabe_ 4y ago
  So are artists all idiots? Storyboards usually don't start with a full script. They start with sketches. Architectural designs start with sketches. Mathematical theorems start with tinkering with equations and notes. Are these people all idiots? Different professions have different methods of "sketching" out ideas. Just because writing is the de facto method of sketching out an idea in the business world, doesn't mean it's the right fit for every profession ever. Most programmers I know feel like writing exploratory code is a form of sketching an idea. I have nothing against writing out your thought process, but it's not desirable or useful in every scenario for writing a program. I was working on some low level multiplayer code about 6 months ago. I spent around 2 and a half weeks researching other methods. Then I spent another week drawing out designs. I was paralyzed because I didn't know what I didn't know. I finally got around to writing the stupidest code, and in 3 days I had an MVP. Yes, this is anecdotal. But I've been paralyzed by design too many times in the past. I would much rather write a rough draft of my code that works, learn a bunch in the process. Then edit it and refine it. Why does writing English have to be the only way to explore a problem? Why is it so difficult to imagine that writing exploratory code is similar to writing a rough draft of a paper? Finally, do research papers get written before they go through the process? No. They do the research, they experiment, then they document the results. I guess these darn researchers are all idiots that didn't realize writing an essay will tell them way more about their research than actual experimentation.
talideon 4y ago
There are a few good reasons why almost every AWS API is on V2. Firstly, the earlier ones were the Wild West and took differing approaches to things. A good example of how things were is SimpleDB, one of their first public APIs, which uses SOAP. Amazon later changed how they did all this, standardising things and switching to JSON for serialisation along with standardising parts of their request and response format, and that means that many went to V2 just because of that. And as somebody who's ex-Amazon, you should know that better than me who's just looking in from the outside. Heck, it could be that somebody pushed them to release something before the details were nailed down. I've had projects like that where we were forced to release an API for general use internally before we were happy with it, which lead to us having to do a V2 that should've been our V1. This happens too. Also, the fact that a service is on V2 doesn't bother me that much. That means that they went through one set of breaking changes after their first public release. If that major version number were higher, I think you might have a point. If they've stuck to that and have just been bumping the minor revision, that means they've just been adding features. > Clearly, documentation is not a silver bullet. It's not meant to be. Nothing is, and that's not the point that's being made. That doesn't mean that it doesn't help an awful lot, even if is agonising torture. If you can't write down what you're doing, you probably don't know or understand what you're doing. Narrow your scope to what you do understand, and specify and implement that. Scope expansion is what minor version bumps are for.

by _gabe_ 4y ago

sumy23 4y ago

> They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that? Isn’t that part of the job? When writing a technical document, you need to research things like dependencies, data storage, caching and estimate expected latency.

_gabe_ 4y ago
The only way to get an accurate estimate of expected latency is to measure it in all sorts of different scenarios. You can't measure something that doesn't exist. And relying on other peoples documentation for accurate latency estimates is asking for trouble. The one thing I've learned through profiling a lot of my code is that my intuitions about how long something will take are always wrong.
- sumy23 4y ago
  Maybe? As an experienced engineer, you should be able to use your experience to estimate the latency. Very few things are truly novel.
  - _gabe_ 4y ago
    As an experienced engineer, you should know that you can never give a good estimate. Very few things are as you would expect them to be. I looked for an article on how to estimate latency. When I Google "how to estimate the latency of my program" the top results are: "Network Latency Guide: How to Check, Test, & Reduce" "How to Measure Latency - Obkio" "How to measure network latency: the 5 best tools - Kadiska" They're all about measuring latency. Honestly I can't find any blog or guide that talks about how to give good estimates. Every time I Google a different variation of this question, it only gives me results that talk about how to measure latency. If you can point me to a good source that talks about how you can provide a good estimate of latency, I would be very surprised ;)
    - pclmulqdq 4y ago
      Use a table of common latencies, add up what's going to happen on your critical path, and multiply by 2. That will be close to your median latency. Edit - when people ask for estimates, they usually aren't asking if it's 1 millisecond or 2 milliseconds. They're asking if it's closer to 1 millisecond or 100 milliseconds.
- pclmulqdq 4y ago
  Part of your job is understanding what is reasonable to expect from your code and understanding how to estimate things. An estimate that is wrong by a factor of 10 can still be very useful. When you get into the weeds on perperformance, a lot of things get very un-intuitive, but from a high level, it is often not hard to estimate median performance figures for a system within a factor of 10.

noobker 4y ago

> what good is documentation without a final product? Reference material for the features and techniques the product had/was going to have. I've earned years of my salary at a time by referencing documentation for vaporware -- things that never quite made it but that had worked out a ton of problems and documented them along the way.

contingencies 4y ago

This question is well discussed. A lot of the problems that exist in software, a lot of the problems that one encounters in writing... in building a system, in writing a program: those are problems that are caused by not thinking about what you are doing before starting to code. - Leslie Lamport An idiot with a plan can beat a genius without a plan. - Warren Buffett No battle was ever won according to plan, but no battle was ever won without one. - Dwight D. Eisenhower To think, you have to write. If you're thinking without writing, you only think you're thinking. - Leslie Lamport Anything you do is an iterative process. You start out by thinking about something, and then you start writing it, and in the course of writing it, you rewrite and you rewrite and you rewrite. - Leslie Lamport ... via https://github.com/globalcitizen/taoup https://github.com/globalcitizen/taoup PS. Full disclosure: I spent today rewriting something I coded yesterday... but generated a lot of written pages before starting both days! (It's a nontrivial problem. I do planning on paper because it's faster.) Now it's mostly there and well documented.

_gabe_ 4y ago
So are artists all idiots? Storyboards usually don't start with a full script. They start with sketches. Architectural designs start with sketches. Mathematical theorems start with tinkering with equations and notes. Are these people all idiots? Different professions have different methods of "sketching" out ideas. Just because writing is the de facto method of sketching out an idea in the business world, doesn't mean it's the right fit for every profession ever. Most programmers I know feel like writing exploratory code is a form of sketching an idea. I have nothing against writing out your thought process, but it's not desirable or useful in every scenario for writing a program. I was working on some low level multiplayer code about 6 months ago. I spent around 2 and a half weeks researching other methods. Then I spent another week drawing out designs. I was paralyzed because I didn't know what I didn't know. I finally got around to writing the stupidest code, and in 3 days I had an MVP. Yes, this is anecdotal. But I've been paralyzed by design too many times in the past. I would much rather write a rough draft of my code that works, learn a bunch in the process. Then edit it and refine it. Why does writing English have to be the only way to explore a problem? Why is it so difficult to imagine that writing exploratory code is similar to writing a rough draft of a paper? Finally, do research papers get written before they go through the process? No. They do the research, they experiment, then they document the results. I guess these darn researchers are all idiots that didn't realize writing an essay will tell them way more about their research than actual experimentation.

talideon 4y ago

There are a few good reasons why almost every AWS API is on V2. Firstly, the earlier ones were the Wild West and took differing approaches to things. A good example of how things were is SimpleDB, one of their first public APIs, which uses SOAP. Amazon later changed how they did all this, standardising things and switching to JSON for serialisation along with standardising parts of their request and response format, and that means that many went to V2 just because of that. And as somebody who's ex-Amazon, you should know that better than me who's just looking in from the outside. Heck, it could be that somebody pushed them to release something before the details were nailed down. I've had projects like that where we were forced to release an API for general use internally before we were happy with it, which lead to us having to do a V2 that should've been our V1. This happens too. Also, the fact that a service is on V2 doesn't bother me that much. That means that they went through one set of breaking changes after their first public release. If that major version number were higher, I think you might have a point. If they've stuck to that and have just been bumping the minor revision, that means they've just been adding features. > Clearly, documentation is not a silver bullet. It's not meant to be. Nothing is, and that's not the point that's being made. That doesn't mean that it doesn't help an awful lot, even if is agonising torture. If you can't write down what you're doing, you probably don't know or understand what you're doing. Narrow your scope to what you do understand, and specify and implement that. Scope expansion is what minor version bumps are for.