On 3/8/06, Brad O'Hearne <[EMAIL PROTECTED]> wrote: > I know you are speaking tongue in cheek, but on the serious side, if > there is any serious belief that an absence of documentation is a good > encouragement to become a developer -- it isn't. It will relgate and > thin the user base to those who can invest developer-level quantities of > time, rather than also including those who want to be merely a user. And > as I'd guess developers generally start out first as users, it probably > doesn't help add new developers to the mix. If someone knows day 1 they > are going to have to invest significant amounts of time just to get > something to work, it creates more justification for building a custom > component which can be tailored to all needs, rather than using a > general tool, which may or may not meet all needs.
You're taking this to an extreme, but correct nonetheless. > I strongly disagree. Documentation (as well as code) should meet the > intended design. If the documentation based on expected functionality > diverges from the actual functionality of the code, there is a bug. But > if you document the bug as if it were expected functionality, your user > base is going to build against and adjust to the bug, as if it were > expected functionality. Your user base will also not be able to > recognize what is a bug and what isn't, and therefore won't be reporting > these things, as the documentation supports the function. Ok, fair point. It's really what we do in practice, anyway. If a doc explains a bug as if it is desired behaviour, that should red flag it for the developer who has to apply that patch and realise that there is a bug to fix and the contributed documentation needs adjusting. Honestly, I don't think this happens all that often, and is not a major hinderance to someone contributing. Usually, its obvious when it doesn't work as intended. > Yes -- knock it back. Its all about completeness, and holding to a high > standard. Because people gripe doesn't mean the bar should be lowered. > And consider what that gripe means: "I don't wanna document." Is that a > good reason not to document? The problem is the perception that code and > documentation are somehow separate entitties -- that code is the product > and documentation is this other optional thing. They aren't separate, > they are both integral parts of a component, and until both exist, a > component is not complete. It's worth encouraging, but I also realise that it would be completely hypocritical at this point to accept contributions without docs and tests. I've already said its my personal ambition to correct that. We need to fix the problem in the community first before clamping down on it. I think at this point we can say we reject things that don't meet the *current* quality of docs and tests - which means in a few areas things have been sent back for further review. > Its the last thing I want to do. I'm here obviously for a reason. It > isn't about ownership, just getting the job done. Maven is great, its > just a shame that from a user standpoint, a lack of documentation > undermines the usefulness of the product, and gives justification for > not using Maven, rather than using it. I think we agree on all the points, but I think you've also taken everything to an extreme - the situation is not quite as dire as it seems from these discussions (as evidenced by continued growth, stunted though it may be by this issue), and the alternative still feels a little utopian. We can't leap to where we are now to perfection - practical baby steps are needed. At the moment, we agree on that fundamental point that it needs to be fixed, and are discussing whether it's as bad as you say, really. It's hard not to get drawn into that because it does feel like an attack on our work, and particularly hard because we've done more documentation than new features since October (though both outweighed by bug fixes). As I've said earlier, I think this thread is entirely unproductive because we know we need to improve, but we can't leap there from here. Instead I'll be starting a thread on the dev@ list to see what we should be doing about how we can improve it going forward. Feel free to contribute there on the practical steps. And again, thanks for your concern. If you have time to contribute to this, it would be extremely welcomed. - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
