[atoav]

I just write documentation because I know future me would like to have it. That is just good engineering.

If you are an electrician you also label your terminals and add plans to avoid troubles for other electricians and your future self. People who don't do that are handymen, but not electricians.

Many developers are handymen, not engineers.

[colordrops]

Yes, and the electrician doesn't insist on everyone reading all the labels and plans on delivery. They are meant to be references, used at a future time they are needed.

[marrs]

Documentation is there to help you understand your project now. If you’re using documentation only as a historical reference then you’re using it wrong.

[gregoriol]

Documentation is there to help you (or someone else) understand the project that you haven't been working on for 6 months and it goes back alive. You'll be very happy to have things written down: nobody will remember why this thing does that, or how to restart the damn tool.

[marrs]

Yes, and it's also there to help you now. I think a lot of people in this thread are underappreciating the art of writing.

When you write your thoughts down, you can then read them back to yourself. Then you can see all the flaws and gaps in your thinking. Then you can edit your document to refine your thinking. And if you work on a team, you can then share this best-representation of your thoughts with your colleagues and get their feedback. If you're not doing this then you're almost certainly not creating optimal designs.

Maybe you think this is all overkill, and maybe it is some of the time, but I can't tell you how much stupid code I've read that was written by smart people who weren't thinking clearly.

[eru]

Well, documentation has lots of uses. This is a very good one for it.

[atoav]

I see this as a positive side effect. Usually I understand the project now, this might not be truw for other people or even myself in the future.

Using documentation to clarify concepts as I go is certainly aomething that happens, but it is not the reason i do it.