[tsally]

Personally I'd rather someone not write an opensource project than write it and not document it. Understanding someone else's thought process is hard and it gets to be an order of magnitude more difficult without documentation. If it's easier for your average hacker to write his/her own implementation than use your library, you've failed.

[BrandonM]

I really doubt that's true. You're saying that instead of using a poorly-documented mencode filter to fade a video in and out, you'd rather have to write your own filter or not be able to use mencode for the job at all?

While working on a project with a tight deadline, I've needed complex functionality that wasn't well-documented, and I've needed complex functionality that wasn't there. When it wasn't there, I was forced to produce complex functionality that wasn't documented. If I'm generous enough to release that for others to use, reference, and modify for free, then the last thing I want to hear is somebody bitching about how I didn't document it well enough for them. I have other things to do, and for me it was a one-off project.

In a pinch, source code is documentation, and it's pretty hard to make an argument that undocumented source code is worse than nothing at all. At least then when you're implementing your nicely-documented tool (because you'd rather have documentation than get stuff done), you'll have a reference implementation to look at and test against.

Note: I'm not arguing that documentation isn't important, I absolutely agree that it is. I just think it's absurd to rank the importance of documentation above the stuff that it's documenting.

[tsally]

It's my personal preference, so it's true whether you doubt it or not. :-p

Using undocumented code is like programming in a language I hate. Mentally it's a really shitty experience and I'm not in a position where I have to settle for that. If I needed to do it to put food on the table, obviously I would.

You're also creating this false dichotomy between getting stuff done and documenting your code. I've never been in a position to have to choose between the two. If you have time to write a good program but not enough time to document it, I would question whether the program you wrote is actually good. If I'm writing a paper, sure I can spew shit out on a page for a couple hours and produce a "paper". But realistically if I'm actually going to produce a paper I need time for outlining and proofreading.

(Note that "documentation" isn't really what matters, it's that the code is understandable. If the code is self-documenting or the program is small enough, I consider that documented code.)

[BrandonM]

Quite often, "getting stuff done" and documenting your code is two separate steps. The example I made up above was not something I pulled out of the air. I've been doing a lot of different little jobs for a client, and one of those was to create a program that could automatically publish a finished video based on a raw video input (adding an intro and outro sequence, fading in and out, etc.). To do that, I used ffmpeg.

ffmpeg had recently dropped support for an old filter system and began using a new, not-fully-fleshed-out system. The filter creation process was pretty well documented, and there were a few well-documented filters. There was a filter or two that I needed which was documented poorly but had a couple usage examples, just enough to get me going. I was very grateful for these! Then there were a few filters I needed that weren't there. I had to write them, which involved some level of trial-and-error to get working correctly.

My line of work is not video filters. The work I typically do for clients does not involve video processing. If I quote a client an amount for a job, the more time I spend on a one-off job, the more money I'm subtracting from my hourly, and the longer until I move onto the next job. Quite literally, I can get more stuff done, or I can document something that I'll never use again.