Hacker News Reader

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

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.

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.

> So are artists all idiots?

No, and GP didn't remotely imply anything like that. In fact, your examples are exactly backwards. Let's take the quote you're likely referring to.

> An idiot with a plan can beat a genius without a plan. - Warren Buffett

When an artist sketches, they're creating a rough specification for what they're ultimately going to do. That's the point of a sketch. It might not be _exactly_ what gets made in the end, but it should largely indicative of the end product.

The sketch is your initial specification. Filling in details in the sketch is your MVP. The artwork is the finished product.

People create sketches because they realise they're not geniuses who can just slap paint on a canvas an expect it to work.

> 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?

No, but only if _you_ are the only audience for it. If others, especially others outside of your team are the audience, then you need documentation.

> 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.

You should do both. Write some docs, hit a brick wall, write an MVP to test things out and clarify your thinking, then go back and update the docs with your findings. You know, _iterate_. The problem isn't documentation, but that you fell into the trap of Big Design Up-Front.

> 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.

Well, no, that's not how it happens. Researchers don't just write up everything at the end after they've done everything: they need to actually _plan_ the kinds of experiments they do, _plan_ their methodology, _document_ all that. Does this all end up in the paper at the end? No, but it does end up in their lab books, which they're required to keep. Material from those lab books ends up in and edited form of the final paper.

The mistake you're falling into is that you're assuming that this means that _everything_ has to be defined up front. But nobody's actually saying that. Sure, you might have a situation like the one you mentioned previously where somebody will ask you what the minimal latency for X will be, and it's OK to say "I don't know, I'll need a spike to write some kind of MVP to discover that" in response.

That doesn't mean that documenting your intents isn't a good thing.

I agree with what you're saying here. Except what you're saying is the antithesis of what the article is saying.

> The mistake you're falling into is that you're assuming that this means that _everything_ has to be defined up front. But nobody's actually saying that.

This article is entirely focused on the idea that sketching and wireframes are bad ideas. I fundamentally disagree with that. From the article:

> The temptation is to jump straight into building mode, to write code or build wireframes or sketch drafts of what you want to create. The better idea is to write your idea down as a way to think it through and improve upon it. Then, when you start building, you’ll know exactly what to build, and why, and you’ll have pre-written documentation at launch.

> 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.

> 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.

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.

Maybe? As an experienced engineer, you should be able to use your experience to estimate the latency. Very few things are truly novel.

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 ;)

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.

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.

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.