Typing out documentation in code is a little bit like rubber duck debugging. It's got all the same psychological truths: putting something into words causes you to think through it and uncover new insights.

That's why I'll type detailed docblocks for interfaces that I'm still designing. Heck, I'll write comments for prototype code that I'll probably delete in a few hours, and no one will ever see it.

People don't think in code no matter how much experience they have. Code is simply how we direct computers to solve the problem that we have in our heads. It can't be the canonical solution to the problem at hand. For features of sufficient complexity, that solution is nearly always defined somewhat abstractly: render a bar chart, send a summary email, recognize a face in an image. The code we write is our best approximation of that abstract concept into the limited language of computers. The bugs that show up in our code are the error bars of that approximation.

So when we're architecting a new feature, we can't just start by writing code alone. We have to deeply think through how that code should be structured. What interfaces, method signatures, and object types are best suited to implement this abstract idea? How to do they go together? Why this design instead of another one? Documenting on the fly helps us to put these ideas into words and refine them to a better design. And sometimes that means typing out three paragraphs in a docblock for a class that you'll delete ten minutes later when you realize it doesn't make sense.

In a world where we're trying to wrap up sprint tasks, hit launch deadlines, and check off deliverables, this feels wrong. If something's not delivering specific and measurable value, then we should avoid it--right? That's the kind of mindset that works great when you're only supposed to be a cog in a machine or another step on an assembly line. But for most engineers in tech today, we're in a position of authority to push recommendations, make architectural calls, and run our little kingdoms the way we see fit (as a team, of course). It's worth it to write documentation that will be thrown away--it's a necessary sacrifice for the design that'll come after it.

I'll admit that this is somewhat of a life platitude for me: I'm convinced that there's value in doing just about anything, solely because I'll learn something from it. Even if nothing else comes from it, I've gained experience and insight into something that I didn't have before.