Write the documentation first
Write the documentation first
Published: May 11, 2026
2026-05-11
Tagged:
data-science
development
science
2026-05-11 00:00:00 -0400<br>James Hawley
data-science
development
science
I’ve worked on all kinds of research, data science, and software projects.<br>Each time I start a project, I’m compelled by the urgency of others, or by my own motivation, to “just start working”.<br>Just get a proof-of-concept.<br>Just get a report finished.<br>Just send a message to this person.<br>Every time I “just” start a project this way, I come to regret it.
This desire for urgent action is a fallacy that rarely truly needs action right away1.<br>If something is important enough that you need to carve out dedicated time for it, but simple enough that the word “just” is warranted, someone else would have already done it.
It is far more effective, in my opinion, to start writing about the work.<br>What were we specifically asked to do?<br>Who asked us to do it?<br>Why did they ask us to do this thing?<br>Why did they ask us to do this thing?<br>Does our impression of this project match what we know about the topic?<br>What existing data do we have available?<br>Do we have any prior art to use as examples or a starting point?<br>Thinking about questions, writing them down, and using the process to figure out the scope of your project is always an excellent use of your time.
The first reason I prefer thinking before doing is that I don’t waste time doing unnecessary things or fixing mistakes.<br>You’ve got a proof-of-concept working?<br>Alright, let’s stress-test it.<br>What’s that?<br>You didn’t design it for the throughput that we need?<br>Let’s go back to the drawing board with this requirement in mind and erase a lot of your proof-of-concept work.<br>Thinking and talking about an idea before starting would have raised this requirement as necessary.
The second reason I always regret “just” starting is that there never seems to be enough time to do it afterwards.<br>I never work on something that is for its own sake — it’s always in service of some bigger, more important task we’re trying to accomplish or question we’re trying to answer.<br>Once the initial work is done, it’s onto the next thing.<br>I rarely am afforded the time to fix up all the things I didn’t get to, which means I (or the people I’m working with) are the only ones who will ever have knowledge of how this thing works.<br>It’s not written anywhere else, so why should anyone expect to have an understanding of how this undocumented project works, what its purpose is, or what its limitations are?<br>And if the original authors couldn’t even be bothered to document it, why would anyone else even be bothered to use it?<br>If you bake in the documentation at the beginning, it is already part of the work and you don’t have to tack it on, afterwards.
This will counter-intuitively slow down the beginning of the project.<br>You’ve spent a couple of days on the idea but don’t have any working code to show for it.<br>But what you lack in digital artifacts you will have in understanding2, which will be far more valuable in the long run.<br>Understanding gives you the context you need to solve problems quickly, effectively, and sufficiently.<br>Understanding gives you a sense of goals, limitations, and stopping criteria.<br>Understanding gives you an ability to pick a reasonable starting point and justify all the steps you’re going to take next.<br>All of those things are crucial for a successful project, no matter the size or urgency.
There is a risk that you’ll misunderstand something or the project’s scope will change beyond your control and you’ll need to throw the documentation away.<br>In my opinion, that’s fine, and is very different to throwing away code or results.<br>You will have benefited from understanding the new set of problems and questions, even if you didn’t do any “work”.<br>If that project is still important and someone else picks it up, they will benefit from the thinking and writing you’ve done.<br>Code, figures, and other artifacts are the means to an end.<br>Insights and answers to important questions are far more important.
Reject the impulse to start working right away.<br>Slow down, reason about it, then when you feel comfortable with the problem, you’ll probably have a few good ideas about what to do next and how to do it.
Footnotes
I’m not talking about working in a hospital or in the service industry, where urgent, immediate action is often required. ↩
And understanding is your job. ↩