> "for some writing code itself is an act that clarifies the still-murky concepts and helps to produce a good writeup."

This is my philosophy after ~2 years of working on distributed systems. I got sick of vague design discussions where everyone has a 5 minute memory.

I am much happier to sit at my desk and figure it out by writing code, then produce a design doc once I have a solid prototype working. It feels more honest and real.

At the same time, I wonder if I'm missing out on a different way of doing things.

This reminds me of TDD arguments.

If I'm working within a system I like to code the minimum golden path, add a tests that passes, then add more checks or a new test and go back to the code, etc. Usually the constraints of the system point the way to an obvious skeletal implementation and you can learn as you go along.

On a greenfield project it is especially valuable to have discussions beforehand if people have done something similar before but talking about code at a high level tends to become nebulous rather quickly.

I think the philosophy behind TDD is really valuable in the sense of "start with a goal in mind", but I find that I get better results with running and iterating than going to the effort of writing tests all the way out.

Probably just a mismatch of our testing tools vs the types of things I need to develop usually

For me, it depends on the problem being solved.

If the problem is in a space that we know what the solution 'should' look like, getting as much of that down in the most abstract sense is something I like to do. However that design is only a -proposed- solution, and of course subject to all sorts of changes.

But where things are murky in a design, yeah, sometimes the easiest thing to do is code it out.

In either case, (up to date) diagrams of data flows are one's friend in any distributed system.

I think it depends on the size/scope of what you're doing, how complex it is, and how much novelty (technical and domain) there is in it.

For things that are not terribly new, are small enough to knock out with 1-2 devs, and aren't massively complex, just writing some damn code works really well. But the larger it gets the more useful it is to do some thinking beforehand, especially about the overall architecture, technology choices, potentially tricky error cases, etc. Also it can be particularly useful to flesh out public/widely-used APIs and data storage details, as those tend to be difficult to change once put in place.

That said, I don't think a fully fleshed-out "specification" is useful in most cases. A wiki page, or maybe a few, is usually enough. You just want to spot major problems far enough ahead that you can avoid them instead of running into them.

But hey, YMMV, this is just what I've found. TBH I wish it was different, because I actually _like_ hacking out code more. It's just that thinking ahead _works_ better IME.

I do this a lot too, it works great. For any non-trivial work, we don’t really consider a design doc “good” unless the author wrote a proof-of-concept demonstrating the feasibility of whatever approach is being advocated, specifically focused on whatever is novel or risky with the project. Iterative development starts before the doc is ever reviewed.

As long as when you're writing code, you're solving only immediate problems in a lightweight way, this is the way to go.

Most people, of course, overengineer. I remember being on a project where a guy wrote 5000 lines of code to put two columns in a specific browser.

> I am much happier to sit at my desk and figure it out by writing code, then produce a design doc once I have a solid prototype working. It feels more honest and real

Can relate, every single time I did the opposite, I ended up rewriting anyway because I wasn't following the design doc.

I don't think that writing software is a linear process, as much as us software developers would like it to be. Broadly speaking, there tends to be two approaches. First is documenting and designing. The second is prototyping some code. I actually sit somewhere right in the middle: prototype and use that prototype to inform my document — then I switch back and forth between the two. Really, for me, it's a circular process — not linear.

Most modern software shops don't document at all. They would definitely benefit from writing down a problem statement and description of the solution so that everyone is on the same page.

Documenting doesn't have to mean design-first development, it's a way to make sure you're working the right problems and building the desired solutions before you waste your time writing code.

I've tried to force myself to write something in English before coding, and... it's not 100% followed, but it's often helped. Sometimes I'm not even prescribing the full 'solution', but it's a sketch of the pros/cons of a couple approaches. This can help me remind myself later of why a particular option was chosen, even if it turns out to be bad.

I can't say if anyone else who looks at the code ever also reads what I've written - it seems that generally they don't (even though I announce it and it's in the commit activity stream and PRs).

Writing proper/decent software specification is what, IMO, missing from most modern day software development. The idea is that, someone knowing deep enough what AND how to build, penning down vague ideas as concrete as needed, and hand off the rest to the team. In fact, every engineer need a plan, either for themselves or for the team, either implicit or explicit. Having an explicit plan for a project's development is what I find resulting in a coherent and high fidelity product.

Agile software development is used by many as a disguise of not knowing what to build. Countless hours have been wasted on "iteration". I'm not saying agile is bad. Just that many are adopting agile without knowing why they should