Brett Porter wrote:
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 :)
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.
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.
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.
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.
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 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.
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.
B
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
