Responses below:
Brett Porter wrote:
On 3/7/06, Brad O'Hearne <[EMAIL PROTECTED]> wrote:
I'll reiterate: you cannot document accurately and completely if you
don't know the full scope of feature, which is clearly locked inside the
heads of a few developers.
It takes a lot longer to extract, but everything is in the open in
code here, so I don't think this is entirely fair.
If you have to read source code in order to figure out what something
does, you are effecitvely becoming a developer. You are just traversing
someone else's code vs. coding your own. 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. 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.
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.....
If I could document maven without having to spend months
upon months trying to elicit answers to questions and Googling the great
unknown for Maven 101 information, I probably would.
It would take months and months to document, but if you take small
Then let me ask you -- is there "months and months" of documentation on
the maven web site? The difference is your "example".
We're all suffering the same problem - knowing where to start.
You don't have that problem if everyone documents what they contribute.
As it is, I'm about
a gnat's eyebrow away from writing my own custom alternative to maven.
And how much of a time pit will that be? Although you'll start small,
there's probably 3-4 man years of development in just the current
version of Maven (if not more), and that's if you learn all the
lessons from the products that come before it. Still seem like a good
idea? :)
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.
Sure, you don't do this every time. But imagine the net effect on
documentation we'd have if everyone that wrote these sorts of mails,
or answered a duplicate question wrote it down and put it in the wiki.
And then one person, who can be a developer, or other volunteer, came
and started organising the wiki content where they couldn't before
contribute to the docs.
As a community the net effect of the first option is largely negative.
More than one person is reading and replying to these mails - less
time on something else. 15 minutes on a rough description of something
you just found out saves someone else 2 hours of work. Unfortunately,
there aren't a lot of people willing to do this.
Anyway, that's my own little 'rant'. Back to documentation (and yes,
that's what did get interrupted by this thread).
The only reason this thread exists is because of a need. Raising
awareness of that need isn't negative. It isn't the messenger's fault
that the documentation isn't there, and raising awareness of the need
isn't preventing the need from getting met. The cause of no
documentation isn't because of people posting requesting it, it is
because the documentation isn't there. Shoot-the-messenger isn't going
to help get more people involved. The need for understanding of the app
is a pre-requisite for contribution, which is one reason I brought it
up. 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.
B
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
