Good for you. Don't use my open source stuff. Turns out I wrote it for me, whether you get anything out of it or not doesn't actually affect me. If you do get something out of it, great. If you contribute great. But unless you are paying me, don't tell me what I should be doing with my hobby time. Period, end of story, full stop. Take your demands to someone else.
Further, demands for great documentation are unreasonable. I can point to hundreds of examples of 'well documented' projects where I still dig into the source code and do simple experiments to learn what the heck it does. This is a combination of how I learn and how I use software. Your docs (for all values of you) are crappy and don't tell me how the software works - the code does that tho, so I actually can trust it. If you want to do truely great documentation, put some comments of expected use at the top of the function/class/whatever definition, some comments on tricky sections of code (not "this does the file read" i get that from the call to read(), but "this also triggers an event from the OS handled in foohandler()), and good clean loosely coupled components.
Yeah, see, here's the thing: for many projects of noteworthy complexity, it'll be easier to gain an understanding of how to make use of it through a clear set of docs than it will be by slogging through source code.
Good documentation provides context and use cases. Good comments in source code provide clarity as to what the code is doing. They are in no way equivalent.
One of the benefits of encapsulation in software is that it enables individuals to program against a documented interface without spending (although in many cases I'd say wasting) time to understand the intricacies of implementation. You lose that benefit if you're forced to dip into code to understand how to use that code.
You do have a point, though - as an open source dev, it's your time to spend as you see fit. But a quality open-source project is more than the sum of its code.
> You do have a point, though - as an open source dev, it's your time to spend as you see fit
I agree with both of you - I don't see software as "complete" unless it has documentation, it's part of the package to me. I happen to like writing it, but I hate some other aspects of programming - doesn't mean I skip those sections.
However, I have put things online without documentation before, because the software wasn't complete but maybe someone else would complete it, or find it useful, or learn something from it. Maybe they won't - but I lose nothing by putting it online, and the world stands to gain.
Further, demands for great documentation are unreasonable. I can point to hundreds of examples of 'well documented' projects where I still dig into the source code and do simple experiments to learn what the heck it does. This is a combination of how I learn and how I use software. Your docs (for all values of you) are crappy and don't tell me how the software works - the code does that tho, so I actually can trust it. If you want to do truely great documentation, put some comments of expected use at the top of the function/class/whatever definition, some comments on tricky sections of code (not "this does the file read" i get that from the call to read(), but "this also triggers an event from the OS handled in foohandler()), and good clean loosely coupled components.