On 3/7/06, Brad O'Hearne <[EMAIL PROTECTED]> wrote: > If you have to read source code in order to figure out what something > does, you are effecitvely becoming a developer.
Aha! Our evil plan is realised :) > Furthermore, while you can > determine what a particular section of code does, it does not > necessarily impart what it is *supposed* to do. In other words, if there > are bugs in the code, those will be the basis of the documentation, not > the spec. This will either be obvious when the documentation is written, or just results in two things that need to be corrected if the bug is fixed. Besides, you want the documentation to reflect reality, not what it was supposed to be. > In addition, if the design is convoluted, then you are going > back to the original developer to get information, and now you are > consuming 2 people's time instead of what originally would have been one. But the work isn't doubled. It will take the developer less time than to do it themselves. The work by the contributor saves everyone else a bunch of time. The only person that misses out is the contributor themself, and put that way its amazing anything ever gets done :) > >>The web site doesn't even come close to > >>describing things to the point where someone could follow up with > >>documentation. > > > >Give me an example. > > > I'll answer this request, with your next comment below..... I can answer that, but its not an example of an area where the site doesn't come close (you're just saying it doesn't come close again - we already knew that!) > Then let me ask you -- is there "months and months" of documentation on > the maven web site? The difference is your "example". No, there's probably months, not months and months. I'd say maybe 10% of overall effort, which is clearly not enough. > You don't have that problem if everyone documents what they contribute. So.. we should knock back contributions without documentation? you should see the reaction we get when we try that! Ideally, every contribution should have docs and tests. But I don't think its reasonable to knock it back without it (we should be asking more persistently though, and above all doing it ourselves). This still doesn't address the problem that the developers perception of what is required to understand it is different from everyone else's. It needs iterative improvement. > It seems like a viable idea still. The entire scope of maven's > functionality isn't necessarily needed by everyone. If I'm going to be > invested in an ongoing development effort, then one has to weigh having > 100% ownership and ability to get absolutely every needed feature and > full understanding of the product vs. having to rummage about through > foreign source code, and trial and error to determine how something > works, then possibly discover there is no answer to your problem. It is > a trade-off. One is heavy up-front investment, less long-term, the other > is potentially heavy long-term investement. The better direction remains > to be seen. But going through this experience over the past month has > demonstrated that there's ample opportunity out there for an alternative. If that's what you chose to do, all the best of luck. Of course, if you chose to engage here, contributions are still welcome and you get a big head start. You don't get 100% ownership, but its a meritocracy so if everything you do is in other's best interests, its really no different. > The only reason this thread exists is because of a need. Raising > awareness of that need isn't negative. I may have neglected to say it before, but we already knew. And there's a need for a bunch of other things too. > Shoot-the-messenger isn't going > to help get more people involved. Nobody is getting shot here. But I'll point out that shooting the developer isn't going to yield a whole lot of docs either (on the other hand, ratio of docs to code will stop going backwards). > It seems to me that documentation is more important than source code > and should come first in OSS, because understanding the design opens > the doors for more people to coontribute. Having that knowledge hidden > places a huge barrier to entry for contributors. This part, I totally agree with and is a reason I'm now going back to it. - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
