@josaphatstar said something in a comment thread here this week that I have not stopped turning over.
He documents his projects in short READMEs. He said he has been meaning to do it more properly. Then he named the gap himself: a README describes what a project does once it is finished. It does not capture what it felt like before it worked.
Two kinds of evidence, and they answer two different questions.
The first answers "can I build this?" Slowly, over years. You collect finished things and the answer improves.
The second answers the question that actually shows up when you start something unfamiliar. Not "am I capable." It is "have I been this lost before, and did it pass?"
That one does not accept a portfolio. A finished project is proof you could do the last one, not this one. And the record that would answer it is the record almost nobody keeps, because the moment a thing works it stops looking confusing. Three months on, what took you three weeks reads as obvious, and the evidence that you were ever stuck evaporates exactly when you need it.
So: one line, in the week something finally works. What broke. What fixed it. How long it took. Not a README. A README is for whoever clones the repo next. This is for the version of you who is about to start something new and has forgotten the inside of that feeling.
I keep the same kind of record about writing, and the line that ends up mattering is never the one I expect. Most of what I was sure was the problem turned out not to be.
So what is yours? The thing you were certain was the blocker, before you found out it wasn't.
Top comments (5)
This is an interesting question. It made me think really!
The reason to start a new project for me, is the question or the feeling that if the idea is big and I never built something like that before, and maybe I won't be able to do it.
So, it gives a fire to start the project without thinking in terms of practicality whether its possible or not; or even in a humanly time period.
So, the plus point is I get to start on a project instantly.
Minus point is I don't look if its wasting my time and resources if its really impossible for me.
So, back to the thing, once I reach a point in the project where I can see am progressing for real and if I keep up the work, I will get a finished project,
there comes a twist! Once I know I can do it, I start to think if I can, then why I should worry about it.When ever I want to I will,not now.
So, the initial fire starts fading and I end up with a project that is 40% or 60% or 80% or even sometimes 90% complete.
Like this out of many projects I get 2 to 3 projects near to finished, that I later finish to showcase.
This is a genuinely great piece and strange to see a comment I wrote turned into something this precise. Thank you for that.
To answer your question: I'm almost always certain the technical part will be the blocker. The new framework, the unfamiliar syntax, the thing I haven't learned yet.
It's almost never that. The real blocker ends up being something smaller and less dramatic a misunderstanding about what was actually being asked of me, or a assumption I made early on that quietly broke everything downstream.
I prepare for the fight I expect, and the one that actually shows up is always different.
This is an interesting conversation. When your README lists all your polished projects, it shows that you're a seasoned and experienced dev and not someone who was ever stuck. But maintaining a documentation of it would be a bit tiresome in my opinion so I'm not sure how a dev would be able to use it in their day to day life
Your two-kinds-of-evidence point is why I separate seed work from harvest work. Some of my work is seed work ā small things planted daily that compound if they work at all. I don't judge those by this week's numbers; I judge whether the planting happened. The harvest metrics live on a different clock, and mixing the two clocks made me kill good seeds early.
I was certain it was rhythm, so I built the thing that measures it: how much sentence length varies across a draft. Eight of my own drafts came out between 0.68 and 0.92, against a 0.40 floor I'd been told marked flat prose. All eight passed.
Then a reader lost track of who was speaking on line four.
The number was answering a true question, is this prose alive, and the prose was alive. It was not the question standing between me and someone staying. That one was relational: one character leaning into the sentence, the other leaning away from it. And a habit of mine, welding a clause onto a line to explain what the line had already done, so nobody had to sit in it.
Cut the clause and nothing falls over. That is my test now and it isn't a number. Is this sentence the line, or an explanation of the line.