6 ms·

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 aw

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.

softwaredoug 2y ago
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__ 2y ago
  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 2y ago
    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.
    - __MatrixMan__ 2y ago
      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.
    - oivey 2y ago
      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 2y ago
        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__ 2y ago
        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.
    - fireflies_ 2y ago
      > 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.
      - 2y ago
appleiigs 2y ago
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.
- huijzer 2y ago
  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.)
- jnsaff2 2y ago
  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-get-done https://www.goodreads.com/book/show/61327449-how-big-things-...
  - SaltyBackendGuy 2y ago
    +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.
patrickmay 2y ago
"Writing is nature's way of letting you know how sloppy your thinking is." -- Dick Guindon

softwaredoug 2y ago

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__ 2y ago
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 2y ago
  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.
  - __MatrixMan__ 2y ago
    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.
  - oivey 2y ago
    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 2y ago
      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__ 2y ago
      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.
  - fireflies_ 2y ago
    > 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.
    - 2y ago

appleiigs 2y ago

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.

huijzer 2y ago
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.)
jnsaff2 2y ago
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-get-done https://www.goodreads.com/book/show/61327449-how-big-things-...
- SaltyBackendGuy 2y ago
  +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.

patrickmay 2y ago

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