[ElatedOwl]

Writing is really beneficial for exploring the problem space.

Many times I’ve confidently thought I understood a problem, started writing about it, and come away with new critical questions. These things are typically more visible from the abstract, or might not become apparent in the first few release milestones of work.

I’m reminded of a mentor in my career, who had designed an active/active setup retroactively for a payment gateway. He pulls up a Lucidchart and says “this diagram represents 6 months of my life”.

They’re not always necessary or helpful. But when they are you can save weeks of coding with a few days of planning.

[appleiigs]

I had a boss who had a math degree. He'd map out the flow from start to finish on a whiteboard like you see mathematicians on TV/movies. Always had the smoothest projects because he could foresee problems way in advance. If there was a problem or uncertainty identified, we'd just model that part. Then go back to whiteboard and continue.

An analogy is planning a road trip with a map. The way design docs most are built now, it shows the path and you start driving. Whereas my bosses whiteboard maps "over-planned" where you'd stop for fuel, attraction hours, docs required to cross border, budget $ for everything, emergency kit, Plan A, Plan B.

Super tedious, but way better than using throwaway code. Not over-planning feels lazy to me now

Sure, everyone has a plan until you get punched in the mouth; however, that saying applies to war, politics, negotiations, but not coding.

[jnsaff2]

I the book How Big Things Get Done they analyze big and small project failures and success and end up with something along the lines:

1. Spend as much time in planning as necessary, in the context of mega projects planning is essentially free, maximize the time and value gained in planning.

2. Once you start execution of the plan, move as fast as possible to reduce likelihood of unforeseen events and also reduce costs increases due to inflation, interest paid on capital etc.

[0] https://www.goodreads.com/book/show/61327449-how-big-things-...

[SaltyBackendGuy]

+1 for "How Big Things Get Done". It changed the way I run projects. I got lucky in the sense that I was able to convince my corporate overloads to allow us to have separate Discovery and Delivery goals, on the premise that discovery is cheap and delivery is expensive (the former significantly reduces risk of the latter) and we show our work. Discovery goals come with prototype deliverables that we're ok not shipping to production but most times lay the foundational work to ship the final product. Every single time we've found something that challenged our initial assumptions and we now catch these issues early instead of in the delivery phase.

We've fully embraced the "Try, Learn, Repeat" philosophy.

[CuriousSkeptic]

> convince my corporate overloads to allow us to have separate Discovery and Delivery goals

Since I’m in the middle of trying to do something similar, would love to hear more details. What kind of goals, whats the conflict?

[huijzer]

Yes I have to second that. MLJ.jl is also written by a mathematician and the API is excellent. Truly well thought-out.

(If you think “why does MLJ.jl have so few stars?” please keep in mind that this library was written for the Julia language and not for Python. I honestly don’t think the library is the cause of low popularity. Just wrong place wrong time.)

[ozim]

First you have to have smart people who will be able to foresee design issues.

That’s a bit uncharitable but following this line of thought - you also need those smart people to be confident and communicative.

[marcosdumay]

And for them to be listened to, what is independent on how well they communicate; and for them to be aligned with the most powerful stakeholder, what is almost never the case; and for no big change to happen in an uncontrolled way, what powerful people nowadays seem intent on causing all the time.

[appleiigs]

If you create the plan like a mathematical formula like my boss did, the evidence becomes irrefutable... like a mathematical proof. The article does mention that the plan is communication tool.

[ozim]

Everywhere I worked technically correct and irrefutable facts were enough times thrown away and dismissed based on someone feeling or emotion that I don’t believe in irrefutable mathematical proof being communication tool that solves everything.

There had to be something more like just that guys authority or him being majority shareholder or him being super empathetic that he knew how to handle people.

[sevensor]

> however, that saying applies to war, politics, negotiations

It’s not even an argument against planning. You’d be a fool to go to war without a plan. The point of the saying is that you’d be a fool not to tear up your plan and start improvising as soon as it stops working.

[zmgsabst]

To borrow another quote:

Plans are nothing, but planning is everything.

The process of building a plan builds the institutional knowledge you need to iterate when inevitably the original plan doesn’t work.

[dbsmith83]

It is kind of an argument against overplanning though, because if your plan that you spent considerable time creating becomes irrelevant, you wasted a lot of time

[fragmede]

That assumes the plan itself is the only useful output from the time spent planning. Even if the plan itself isn't used, the time spent planning means you examined the problem thoroughly, and raised questions that needed answering. Taking the time to think about those questions in order to give a coherent answer is, in and of itself, worthwhile for answering the question later, even if that part's never actually written down.

[dbsmith83]

True, I agree 100%, and that's why I chose to say 'irrelevant' to imply that there was nothing useful about it inherently for those cases. Most of the time, at least in coding, there was probably something useful that came out of it, even if you had to scrap the plan. At the very least, some sort of learning more about the problem space. In the case of war, however, if you lost the war because you over-planned (such as planning one thing very very intricately instead of having several rough plans that leave room for some improv), I'd argue that there probably aren't any residual benefits to celebrate

[DidYaWipe]

I had to do this for a patent application, and likewise found it very useful for identifying holes in my thought process or simply forcing myself to do the functional design work up-front and completely.

It was also great for brainstorming about every feature and functional aspect you can imagine for your product, and making an effort to accommodate it in your design even if it's not MVP material.

[bayarearefugee]

> but not coding.

In my experience it applies to coding when you have any reliance on third party libraries or services and don't have an extensive amount of actual real world experience with that technology already.

[jyounker]

If you have unknowns, then your planning process starts with, "let's figure out how to use this new technology." And that process can involve a bunch of prototyping.

Having to make a choice between "make a design document" or "do prototyping" is a false dichotomy. They're complimentary approaches.

[player1234]

This right here <- is why every discussion in the SWE space is super tedious. Every critique of anything is really just "you are holding it wrong".

Over-planning is impossible if you plan for it, thanks!

[bryanrasmussen]

>Sure, everyone has a plan until you get punched in the mouth; however, that saying applies to war, politics, negotiations, but not coding.

hey, the EU just introduced this new regulation is the software version of getting punched in the mouth.

[lmm]

> Super tedious, but way better than using throwaway code. Not over-planning feels lazy to me now

How was it better? I think a lot of people plan precisely because it feels virtuous, but that's true regardless of whether it's effective or not.

[appleiigs]

My boss would take a piece of data/input and run it through the entire process. It's a string data here, converts to number here, function transforms it here, summarized here, output format there... You wouldn't run into data type issues or have an epiphany that you're missing a data requirement.

[lmm]

If the data transformations are the hard part, sure. But often the hard part is whether you're even outputting the right thing at all. Also, if you're planning in that much detail, you might as well be writing code (perhaps with some holes).

[PittleyDunkin]

> Super tedious, but way better than using throwaway code. Not over-planning feels lazy to me now

Certain projects have too many unknowns to overplan and you need to collect data to construct the assumptions necessary to evaluate the approach.

[bravetraveler]

Man plans and executives laugh

[softwaredoug]

I agree writing is beneficial. But I also find this works with coding. And they go hand in hand for exploring in my experience.

And in the end a good PR has a lot of writing too and has this effect. IMO this sort of well documented draft PR serves as a better design proposal because pure writing causes you to forget important constraints you only remember when you’re in the code.

[__MatrixMan__]

Agreed. You can write prose or implementations or tests beforehand and I don't think it matters too much which you choose, just as long as you give yourself a phase 2 for incorporating the learning you did in phase 1 and put a reality check of some kind in between them.

The only problem with having the draft being implementation is that maybe you'll get pressured into shipping the draft.

[withinboredom]

I’ve had to ship the draft a few times in my career. Usually when the actual code would have been weeks or months more of work (draft has poor architecture, while a proper architecture would have been just as much work as the draft). Twice it was due to showing a demo and a decision maker in the audience said “we can sell this tomorrow” or something to the same effect for that org. In one case, we ran a simple a/b test as a proof of concept on whether to pursue the idea further and it added an extra million bucks a year in revenue. Nobody wanted to wait for a proper implementation. All that code is still in production, slow as shit and nobody wants to fix something that isn’t broken.

If you have a draft, keep it to yourself. Use it as a personal reference when writing the design, or share snippets. Other engineers will realize you have a draft, business people won’t.

[fireflies_]

> In one case, we ran a simple a/b test as a proof of concept on whether to pursue the idea further and it added an extra million bucks a year in revenue.

I'm with the people who decided to ship this. The organization will need to fund more maintenance than they would if they waited, but that has real costs. And "keep your 1mm/revenue idea to yourself" doesn't sound like a healthy engineering culture either.

[withinboredom]

Heh, yeah, that is a special case though. Most people don't work on things that has that kind of impact. If it might, I would suggest going against my own advice.

[oivey]

The time spans for doing it properly or shipping are maybe a bit muddled here, but if you can make a million dollars by shipping something now, you should probably ship it now. If the code is that bad (ie can end up costing way more to maintain than fix) then you should afterward immediately fix it. Side benefit is you’ll probably learn a lot about doing it right from the prod system.

[withinboredom]

Oh we tried to fix it and never succeeded. As soon as other teams found out about it, they started using it too. To be honest, had we waited to do it right, we potentially could have made even more money.

[__MatrixMan__]

I'm not sure what you mean by "should". If your job is to build things that aren't going to fail in ways that later end the company or hurt people, then finding ways to keep the:

> But we could make an additional million next quarter if we ship it now

...crowd in check is probably what you should be doing.

[__MatrixMan__]

I like where your head is at but if you keep it to yourself then you can't get feedback on it.

I once did the draft with ncurses as a hedge against it becoming the real thing. It didn't go over especially well but it was fun.

[patrickmay]

"Writing is nature's way of letting you know how sloppy your thinking is." -- Dick Guindon