dankim.org

We write code, not documents

2020-09-25


Recently a student asked me:

Could you describe one instance where you had to use a diagramming tool (eg. Google Slides Drawings, Lucidcharts, Miro, Whimsical, Gliffy etc) to accomplish a task?

They also provided an example answer I could follow, which consisted of creating a chart to map a user flow, presenting it, getting feedback, adding it to another larger document, and creating Jira tickets.

I was a little surprised (though simultaneously not surprised) — is this how software development is still being taught?

Without being critical of academia, this seemed like a good opportunity to try to shatter by-the-book software development ideas for some future engineers by sharing a different way — our way.

Here was my answer (slightly edited for clarity and typos):

I hope this answer is helpful, but I actually don’t use a lot of diagramming tools, and I think it’s safe to say they’re not commonly used at Basecamp. We don’t write specs and stuff like that as they’re not “real” enough. We will do high level sketches and rough drawings (usually pen and paper or an iPad and a sketching app), but that’s typically it. So more often I’ll grab a pen and paper and sketch out a rough flow of what I need to do, or write out pseudo code of the steps that I need to take.

The reason we don’t get too formal about diagramming is because they’re often not close enough to reality. You can draw and draw, but the reality is until you start writing some code or implementing a design, you don’t know what you’re going to hit. Maybe you’ll hit a technical limitation or maybe something just flat out doesn’t work. All the diagrams in the world don’t get you closer to finding out that stuff. So the sooner you get to real code, the sooner you‘ll get to seeing what’s possible. Fast and iterative in real code is where you want to be, not locked into a document.

With regards to frequency, I’d say I do that about every day. Because it’s so lightweight, there’s no barrier to entry. I’ll draw out what I need to do or write out the steps and then get to it. Very often I’ll hit something unexpected and then redraw what I need to do. It’s fast and iterative, and nothing is written in stone (because in software nothing is ever written in stone!)

Whether you agree or disagree with our way of software development, it’s an honest assessment of how we’ve done things at Basecamp for a long time. And I’d say all things being equal, it’s worked out pretty well for us. 😉