You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Simon Kitching <sk...@apache.org> on 2006/03/07 03:27:27 UTC
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
On Mon, 2006-03-06 at 18:36 -0700, Brad O'Hearne wrote:
> Simon Kitching wrote:
>
> >Documentation is always last for developers :-). As it happens, however,
> >it is the area that *users* can productively contribute back to a
> >project.
> >
> >
> Aside from documenting "things I found along the way", I disagree. First
> of all, you have to have the information to produce documentation.
> Acquiring this information requires the time of the developers -- there
> is no reason for them to be dictating to someone, just write the
> documentation. If the users knew the information already, the need for
> documentation wouldn't be so dire. Second, relying on users for
> documentation guarantees that documentation will always be an
> after-the-fact effort. It should never be this way. Third, with the
> already pointed-out pace of change, the documentation is virtually
> guaranteed to always lag behind current feature and be inaccurate.
>
> For a product released to the public, open source or not, documentation
> should be there, accurate, and clear. The only reason for poor
> documentation in any project is choice. Its just a reflection of the
> level of excellence to which the project aspires -- and this is any
> project, not just this one. The problem is that people have in this
> equation in their head:
>
> code == product.
>
> This is inaccurate. The real equation is:
>
> code + documentation + support == product
>
> Look at it this way, and there would be less focus on bells and
> whistles, and more focus on documentation and support of the product.
I don't agree at all.
First of all, non-funded open-source projects (which is what this is)
are usually done because someone needs a tool *themselves*. That person
clearly does *not* need documentation. If *you* need documentation,
that's not the problem of the person writing the software. In practice
developers do write some documentation themselves; in some cases the
documentation is very good. However it's not something that a user
community can *demand* of the unpaid creators of a tool. And neither can
we users demand that the developers delay releasing functionality they
want because they haven't documented it enough for us to use.
Secondly, this is open source. If you really want to know how a
particular piece works, read the code. It's the final and official
documentation. Nothing is being hidden from any user of the software.
Thirdly, documentation is *never* complete. There's always someone who
doesn't understand a topic, or who wants to do something out of the
ordinary. I'd consider your request to package dependencies of a module
inside the jarfile as an example of that. It would be frustrating to see
new functionality kept unreleased because *some* of the potential users
are not able to understand it or want to use it in unexpected ways.
And fourthly, the developers are often *not* the best people to write
the documentation. For someone who knows all the details of an
implementation it's quite hard to step back and write good introductory
tutorials.
Just about every successful commercial product ever released has had
books about it published *months to years* after the product was
released. MS-Office tutoruals, RedHat administration guides, Hibernate
"developers notebooks". Continuing the documentation process after the
product is released is *normal*.
The most important piece is the first, though. As users we shouldn't
demand but instead contribute. Updating the main site directly isn't
possible, but improving documentation via a wiki is.
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by "Calen Martin D. Legaspi" <ca...@orangeandbronze.com>.
+1
I think we've been spoiled by the open-source projects that are funded by
big companies, that may have paid technical writers. In my use of a lot of
other open-source software, such as linux utilities, I've relied on mailing
list archives, forums and unofficial How-Tos on blogs of people not
connected to the development team.
I believe the crux of open-source is contribution, and so if one wants good
documentation, one should think about wrting it himself. This doesn't have
to be such a big effort. Replying to mailing list questions or recording
your discoveries in a blog are incremental ways to contribute.
--
Calen Martin D. Legaspi
Sun Certified Enterprise Architect
Software Engineering Director, Orange & Bronze Consulting, Inc.
President, PinoyJUG - "Developers building community." -
http://groups.yahoo.com/group/pinoyjug
The Third World Developer Blog: http://calenlegaspi.blogspot.com
On 3/7/06, Simon Kitching <sk...@apache.org> wrote:
>
>
> First of all, non-funded open-source projects (which is what this is)
> are usually done because someone needs a tool *themselves*. That person
> clearly does *not* need documentation. If *you* need documentation,
> that's not the problem of the person writing the software. In practice
> developers do write some documentation themselves; in some cases the
> documentation is very good. However it's not something that a user
> community can *demand* of the unpaid creators of a tool. And neither can
> we users demand that the developers delay releasing functionality they
> want because they haven't documented it enough for us to use.
>
> Secondly, this is open source. If you really want to know how a
> particular piece works, read the code. It's the final and official
> documentation. Nothing is being hidden from any user of the software.
>
> Thirdly, documentation is *never* complete. There's always someone who
> doesn't understand a topic, or who wants to do something out of the
> ordinary. I'd consider your request to package dependencies of a module
> inside the jarfile as an example of that. It would be frustrating to see
> new functionality kept unreleased because *some* of the potential users
> are not able to understand it or want to use it in unexpected ways.
>
> And fourthly, the developers are often *not* the best people to write
> the documentation. For someone who knows all the details of an
> implementation it's quite hard to step back and write good introductory
> tutorials.
>
> Just about every successful commercial product ever released has had
> books about it published *months to years* after the product was
> released. MS-Office tutoruals, RedHat administration guides, Hibernate
> "developers notebooks". Continuing the documentation process after the
> product is released is *normal*.
>
> The most important piece is the first, though. As users we shouldn't
> demand but instead contribute. Updating the main site directly isn't
> possible, but improving documentation via a wiki is.
>
> Regards,
>
> Simon
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/8/06, Brad O'Hearne <br...@neurofire.com> wrote:
> If requesting documentation commensurate with current maven feature, in
> tandem with compliments for the maven code itself, is considered "an
> attack on our work" then I give up.
That wasn't my intent with that point, sorry.
> I think the real point, as evidenced
> by the typical "we know, we know" and "if you want doc, write it
> yourself" responses both on the mailing list and IRC, is that raising
> the issue of documentation is a nuisance.
I don't think so at all, I just felt that we'd probably well and truly
covered the topic. We ended up with a few helpful points in the end,
it just seemed to difficult to boil the discussion down.
> I don't generally view things
> that way -- its all opportunity, and the more voices on a particular
> issue, it possibly lends more weight to the need, which I would think
> would be a valuable source of direction to developers. But others I
> suppose will choose to view it just as an isolated complaint, and
> something they don't want to hear. Difference in people, I guess.
I don't think anyone suggests this is an isolated complaint.
> I've contributed a new plugin, and mods to two existing plugins, and
> also posted some time ago about how I could go about documenting maven
> myself from beginning to end on this mailing list. Unless I missed a
> helpful response, the responses I received didn't give me any direction
> for doing this other than just reading code and existing doc. My
> definition of "extremely welcomed" goes a little beyond this.
Well, that's an attitude we'll need to fix then. I'll look back for
your post and issues as I and others may have missed or forgotten it
or been otherwise distracted at the time.
> I'm really out of words on this, and at any rate, you've made clear you
> feel this discussion is a waste of time, so I'll oblige, and drop it.
I just said I was moving it to the dev list to try and start practical
discussions. I don't think anything is getting dropped.
> Back to using maven. I really do appreciate that you've shared your
> views on this, despite your disagreement with mine.
Thanks, ditto.
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/8/06, Brad O'Hearne <br...@neurofire.com> wrote:
> I've contributed a new plugin, and mods to two existing plugins, and
I see your patches were applied, apart from the new Mojo for JBoss WSR
files. It's hard for us to take that on when we don't use it ourselves
and there isn't a lot of interest from others. If you find a few other
people who are able to contribute to it, we can probably move that
forward.
> also posted some time ago about how I could go about documenting maven
> myself from beginning to end on this mailing list. Unless I missed a
> helpful response, the responses I received didn't give me any direction
> for doing this other than just reading code and existing doc. My
> definition of "extremely welcomed" goes a little beyond this.
I'm afraid I can't find that in gmail. Can you point me in the right
direction? (An exact subject title should do the trick - thanks).
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
Brett Porter wrote:
>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,
>
>
If requesting documentation commensurate with current maven feature, in
tandem with compliments for the maven code itself, is considered "an
attack on our work" then I give up. I think the real point, as evidenced
by the typical "we know, we know" and "if you want doc, write it
yourself" responses both on the mailing list and IRC, is that raising
the issue of documentation is a nuisance. I don't generally view things
that way -- its all opportunity, and the more voices on a particular
issue, it possibly lends more weight to the need, which I would think
would be a valuable source of direction to developers. But others I
suppose will choose to view it just as an isolated complaint, and
something they don't want to hear. Difference in people, I guess.
>And again, thanks for your concern. If you have time to contribute to
>this, it would be extremely welcomed.
>
>
I've contributed a new plugin, and mods to two existing plugins, and
also posted some time ago about how I could go about documenting maven
myself from beginning to end on this mailing list. Unless I missed a
helpful response, the responses I received didn't give me any direction
for doing this other than just reading code and existing doc. My
definition of "extremely welcomed" goes a little beyond this.
I'm really out of words on this, and at any rate, you've made clear you
feel this discussion is a waste of time, so I'll oblige, and drop it.
Back to using maven. I really do appreciate that you've shared your
views on this, despite your disagreement with mine.
Cheers,
Brad
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/8/06, Brad O'Hearne <br...@neurofire.com> 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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
Brett Porter wrote:
>On 3/7/06, Brad O'Hearne <br...@neurofire.com> 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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
Jeff,
Well spoken. I completely agree.Everyone should realize that when you
don't get user docs, you *are still* waiting a week or two or three,
because you'll end up sinking that time into figuring it out how
everything works, so you certainly aren't coming out ahead by throwing
things out without documentation. In addition, this is going to result
in the mailing lists being flooded with questions on undocumented
feature that would otherwise not be, and is going to raise the
frustration level of every user that struggles to get the undocumented
feature to work.
Brad
Jeff Jensen wrote:
>Yes you should. +1. I would rather wait another week or two or three for a
>new feature with user docs than have the current path of docs not
>materializing often enough.
>
>And reject same for no tests.
>
>Code + tests + docs = valid contribution.
>
>Make your stance, clearly document this on the "How to Contribute" page.
>Reject away.
>
>
>-----Original Message-----
>From: Brett Porter [mailto:brett.porter@gmail.com]
>Sent: Monday, March 06, 2006 11:55 PM
>To: Maven Users List
>Subject: Re: Maven documentation (was Re: how to include all dependencies in
>your jar)
>
>
>
>
>>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.
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
>For additional commands, e-mail: users-help@maven.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Jeff Jensen <je...@upstairstechnology.com>.
Yes you should. +1. I would rather wait another week or two or three for a
new feature with user docs than have the current path of docs not
materializing often enough.
And reject same for no tests.
Code + tests + docs = valid contribution.
Make your stance, clearly document this on the "How to Contribute" page.
Reject away.
-----Original Message-----
From: Brett Porter [mailto:brett.porter@gmail.com]
Sent: Monday, March 06, 2006 11:55 PM
To: Maven Users List
Subject: Re: Maven documentation (was Re: how to include all dependencies in
your jar)
> 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/7/06, Brad O'Hearne <br...@neurofire.com> 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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
Responses below:
Brett Porter wrote:
>On 3/7/06, Brad O'Hearne <br...@neurofire.com> 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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
POM Reference page updates (was RE: Maven documentation (was Re: how to include all dependencies in your jar))
Posted by Jeff Jensen <je...@upstairstechnology.com>.
Nice improvements Brett, thank you.
This is turning into a very nice reference document. It is vastly improved
over recent time with your and others checkins.
(so everyone please file JIRAs for items that still need improvement! :-)
-----Original Message-----
From: Jeff Jensen [mailto:jeffjensen@upstairstechnology.com]
Sent: Tuesday, March 07, 2006 8:18 PM
To: 'Maven Users List'
Subject: RE: Maven documentation (was Re: how to include all dependencies in
your jar)
Thanks Brett.
Reopened http://jira.codehaus.org/browse/MNG-1479.
-----Original Message-----
From: Brett Porter [mailto:brett.porter@gmail.com]
Sent: Tuesday, March 07, 2006 12:23 PM
To: Maven Users List
Subject: Re: Maven documentation (was Re: how to include all dependencies in
your jar)
Thanks. I think someone took a pass at this recently, but it could
definitely use some more (and probably an improved presentation). Can you
articulate that in a JIRA entry?
(I prefer folks that suggest things file their own so they get to see it
followed through to completion and take a little credit for pointing it out.
If you'd rather I just file it myself, just say so).
Cheers,
Brett
On 3/8/06, Jeff Jensen <je...@upstairstechnology.com> wrote:
> I suggest starting with getting the POM reference really well
> documented, improving any entries with short, vague explanations.
>
> (And before I receive the "contributions welcome", I did :-). I
> reviewed it for what I understood and saw was vague. I even looked in
> code for values, etc. Now it is time for the next much more expert
> person to do same...)
>
>
> -----Original Message-----
> From: Brett Porter [mailto:brett.porter@gmail.com]
> Sent: Monday, March 06, 2006 11:00 PM
> To: Maven Users List
> Subject: Re: Maven documentation (was Re: how to include all
> dependencies in your jar)
>
>
> We're all suffering the same problem - knowing where to start.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Jeff Jensen <je...@upstairstechnology.com>.
Thanks Brett.
Reopened http://jira.codehaus.org/browse/MNG-1479.
-----Original Message-----
From: Brett Porter [mailto:brett.porter@gmail.com]
Sent: Tuesday, March 07, 2006 12:23 PM
To: Maven Users List
Subject: Re: Maven documentation (was Re: how to include all dependencies in
your jar)
Thanks. I think someone took a pass at this recently, but it could
definitely use some more (and probably an improved presentation). Can you
articulate that in a JIRA entry?
(I prefer folks that suggest things file their own so they get to see it
followed through to completion and take a little credit for pointing it out.
If you'd rather I just file it myself, just say so).
Cheers,
Brett
On 3/8/06, Jeff Jensen <je...@upstairstechnology.com> wrote:
> I suggest starting with getting the POM reference really well
> documented, improving any entries with short, vague explanations.
>
> (And before I receive the "contributions welcome", I did :-). I
> reviewed it for what I understood and saw was vague. I even looked in
> code for values, etc. Now it is time for the next much more expert
> person to do same...)
>
>
> -----Original Message-----
> From: Brett Porter [mailto:brett.porter@gmail.com]
> Sent: Monday, March 06, 2006 11:00 PM
> To: Maven Users List
> Subject: Re: Maven documentation (was Re: how to include all
> dependencies in your jar)
>
>
> We're all suffering the same problem - knowing where to start.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
Thanks. I think someone took a pass at this recently, but it could
definitely use some more (and probably an improved presentation). Can
you articulate that in a JIRA entry?
(I prefer folks that suggest things file their own so they get to see
it followed through to completion and take a little credit for
pointing it out. If you'd rather I just file it myself, just say so).
Cheers,
Brett
On 3/8/06, Jeff Jensen <je...@upstairstechnology.com> wrote:
> I suggest starting with getting the POM reference really well documented,
> improving any entries with short, vague explanations.
>
> (And before I receive the "contributions welcome", I did :-). I reviewed it
> for what I understood and saw was vague. I even looked in code for values,
> etc. Now it is time for the next much more expert person to do same...)
>
>
> -----Original Message-----
> From: Brett Porter [mailto:brett.porter@gmail.com]
> Sent: Monday, March 06, 2006 11:00 PM
> To: Maven Users List
> Subject: Re: Maven documentation (was Re: how to include all dependencies in
> your jar)
>
>
> We're all suffering the same problem - knowing where to start.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brett -
I've got to hand it to you. For a "rant", you just seem WAY too calm. :-)
Brian
Brett Porter wrote:
... some good stuff...
Now back to docs! <insert evil laugh or Mad Dog 20/20 here> :-D
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD4DBQFEDRPHaCoPKRow/gARAqzzAJ9wlWLVJIjhLJYr1sIbKl9qUlxMagCVGRdV
LkOPXSCFBAJz4uXWtbt2Xg==
=zuBy
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Jeff Jensen <je...@upstairstechnology.com>.
I suggest starting with getting the POM reference really well documented,
improving any entries with short, vague explanations.
(And before I receive the "contributions welcome", I did :-). I reviewed it
for what I understood and saw was vague. I even looked in code for values,
etc. Now it is time for the next much more expert person to do same...)
-----Original Message-----
From: Brett Porter [mailto:brett.porter@gmail.com]
Sent: Monday, March 06, 2006 11:00 PM
To: Maven Users List
Subject: Re: Maven documentation (was Re: how to include all dependencies in
your jar)
We're all suffering the same problem - knowing where to start.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/7/06, Brad O'Hearne <br...@neurofire.com> 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.
> 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.
> 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
chunks you are concerned with, you'll find someone will take time to
explain it to you in a way that can be done very quickly. If you toss
that in the wiki, someone still needs to come and organise that
information, but its a start.
We're all suffering the same problem - knowing where to start.
> 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 doesn't compute -- for the great product maven is, the lack of
> documentation has turned the experience into a huge time pit. Every
> problem is a new plugin and a new configuration option or file and a new
> frontier of undocumented stuff, and a whole new cycle of trial and error.
And again, *we know* and are trying to correct it. And trying to deal
with other stuff like fixing bugs, applying patches, not to mention
actual jobs and a real life away from the computer. If we dropped
everything and wrote docs for 6 months, people would complain their
bugs haven't been fixed or the features they want aren't being done,
that releases aren't cut and that questions aren't answered. We're
honestly trying to find a balance, and more volunteers are always
welcome.
As you said, this isn't directed at anyone here specifically, because
it happens all the time, so let's do some math with some totally made
up numbers:
Amount of time spent researching problem: 2h
Amount of time spent emailing dev list about the importance of documentation: 1h
Net effect on documentation: 0
(Nobody dropped everything and started writing because they suddenly
realised it was necessary, they already knew).
Now, let's say this happens:
Amount of time spent researching problem: 2h
Amount of time spent emailing dev list about missing documentation: 15min
Net effect on documentation: 15 min
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.
> Let's call it what it is -- the lack of
> documentation is just cutting corners. Its trading away completeness,
> and excellence in a project for what is fun, and/or what we aren't
> willing to wait for.
Agreed, to some extent. But there are equally important things (like
fixing bugs and getting out and having a life) that I'd not like to
cut the corners of. I rarely work on what is fun these days. While I
enjoy it, I drive what I do entirely by priority/time to complete
ratios.
> Whatever is worth doing, is worth doing well.
Couldn't agree more.
Anyway, that's my own little 'rant'. Back to documentation (and yes,
that's what did get interrupted by this thread).
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/8/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> I've submitted two things in regard to this:
> 1. a patch to put at least the correct prefix in the SCM reports
> 2. an issue for maven-project-info-reports (MPIR-33
> http://jira.codehaus.org/browse/MPIR-33) dealing with the automatic
> addition of the artifactId in ScmReport.
Thanks!
> The comment in the POM (which was there before I touched it and remained
> untouched by me) states the following:
>
> <!-- repeated here so that maven-site is not appended -->
>
> which does not work.
Actually it does. It would appended to the URL which was completely
incorrect. The current version just gets you the components trunk
called the wrong thing.
Cheers,
Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brett Porter wrote:
> On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
>> Well... I was going to be all smart and what not - actually give you the
>> source file it's in... but alas - I can't find it. (?)
>>
>> http://maven.apache.org/source-repository.html - both anonymous and
>> developer access.
>
> Ah, I see. This is generated from the POM, but its definitely
> misleading. We need to do something about that. I'll file under
> Maven's project info reports.
>
> - Brett
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
>
I've submitted two things in regard to this:
1. a patch to put at least the correct prefix in the SCM reports
2. an issue for maven-project-info-reports (MPIR-33
http://jira.codehaus.org/browse/MPIR-33) dealing with the automatic
addition of the artifactId in ScmReport.
The comment in the POM (which was there before I touched it and remained
untouched by me) states the following:
<!-- repeated here so that maven-site is not appended -->
which does not work.
This still does not address the fact that the report is for maven-site,
while leading someone viewing the site to believe that access via these
means is for the maven code itself.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDbc/aCoPKRow/gARAiZyAKCS0wLwMw31zfsRFJx532mSiB4mvwCggNKk
YxvOo14mG6SWOO9YkQRZg50=
=YW9c
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> Well... I was going to be all smart and what not - actually give you the
> source file it's in... but alas - I can't find it. (?)
>
> http://maven.apache.org/source-repository.html - both anonymous and
> developer access.
Ah, I see. This is generated from the POM, but its definitely
misleading. We need to do something about that. I'll file under
Maven's project info reports.
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brett Porter wrote:
> Both closed. Thanks for pointing them out.
Wow. Okay... I'm feeling better about helping out now. :-D
>
>> I've actually been trying to marry the issue with the site and found an
>> issue (with regard to documentation source) with simply checking out
>> Maven. ($ svn checkout
>> http://svn.apache.org/repos/asf/maven/components/trunk/ maven-site - but
>> maven-site isn't there). So a) this issue is still truly unresolved
>> because the patch hasn't been reviewed/applied, or b) the issue has been
>> resolved because the patch has been reviewed/applied, but Jira hasn't
>> been updated to reflect that. As a "user" who wants to "contribute"...?
>
> Where was that info? The site is at /repos/asf/maven/site/trunk now
> (since about mid last year actually).
>
Well... I was going to be all smart and what not - actually give you the
source file it's in... but alas - I can't find it. (?)
http://maven.apache.org/source-repository.html - both anonymous and
developer access.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDRdbaCoPKRow/gARAqiNAKDMPSXRsvgxSUI6y21EzprpwOuoWACfWuuP
WoDdWcKATsOxsF7Ow1BJIIo=
=OWbv
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> [ever had that feeling some threads could go on forever? ;-)]
:)
>
> As for documentation and Jira... I said I was over there, and this
> relates back to "but...":
>
> MNG-1373 (http://jira.codehaus.org/browse/MNG-1373)
>
> This is the type of thing that makes "contribute if you don't like it"
> daunting. Issue raised back in October. Relates to MNG-1686
> (http://jira.codehaus.org/browse/MNG-1686) from November. Both are
> "Open". Both are "Major". Both unassigned and with patches.
Both closed. Thanks for pointing them out.
> I've actually been trying to marry the issue with the site and found an
> issue (with regard to documentation source) with simply checking out
> Maven. ($ svn checkout
> http://svn.apache.org/repos/asf/maven/components/trunk/ maven-site - but
> maven-site isn't there). So a) this issue is still truly unresolved
> because the patch hasn't been reviewed/applied, or b) the issue has been
> resolved because the patch has been reviewed/applied, but Jira hasn't
> been updated to reflect that. As a "user" who wants to "contribute"...?
Where was that info? The site is at /repos/asf/maven/site/trunk now
(since about mid last year actually).
Thanks,
Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brad O'Hearne wrote:
> You are talking about the difference between an author and an editor to
> some degree. A developer has to document, and that includes being able
> to impart in some form user level documentation if it pertains to what
> they worked on, even if someone else reshapes that into something
> prettier for general consumption. If the developer is unable to
> effectively communicate their contribution, then that is not an issue
> which should alter the project approach; it is an issue which should
> alter whether that developer contributes or not. I find it personally
> hilarious that we place as a prerequiste for a developer fluency in the
> language of Java or C++ and completely discard fluency in the language
> of English. Communication isn't some kind of optional "nice to have";
> its a necessity.
>
> Brad
Agreed. My main point isn't that a developer can't document. Just that
developer documentation is rarely suitable for a project's user
documentation and the more intermediaries there are, the slower that
documentation is 'complete'.
[ever had that feeling some threads could go on forever? ;-)]
As for documentation and Jira... I said I was over there, and this
relates back to "but...":
MNG-1373 (http://jira.codehaus.org/browse/MNG-1373)
This is the type of thing that makes "contribute if you don't like it"
daunting. Issue raised back in October. Relates to MNG-1686
(http://jira.codehaus.org/browse/MNG-1686) from November. Both are
"Open". Both are "Major". Both unassigned and with patches.
I've actually been trying to marry the issue with the site and found an
issue (with regard to documentation source) with simply checking out
Maven. ($ svn checkout
http://svn.apache.org/repos/asf/maven/components/trunk/ maven-site - but
maven-site isn't there). So a) this issue is still truly unresolved
because the patch hasn't been reviewed/applied, or b) the issue has been
resolved because the patch has been reviewed/applied, but Jira hasn't
been updated to reflect that. As a "user" who wants to "contribute"...?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDRCkaCoPKRow/gARAh8EAKCkL+LiPQLAEgt/0xuMviFkQjp48QCgqr7N
j6JSltjUn4ICl+s4Ycjtdr8=
=tfdU
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
One quickie reply:
Brian K. Wallace wrote:
>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA1
>
>Brad O'Hearne wrote:
><snip/>
>
>
>>>And fourthly, the developers are often *not* the best people to write
>>>the documentation. For someone who knows all the details of an
>>>implementation it's quite hard to step back and write good introductory
>>>tutorials.
>>>
>>>
>>>
>>>
>>Absolutely they are. Especially in open source, they are the ones who
>>know how something works, and is supposed to work. You cannot have
>>someone who doesn't understand the product document it. What you are
>>referring to is the inability of many developers to communicate concepts
>>effectively, which is an entirely different issue. If a developer can't
>>communicate their thoughts, well then, that's something they need to
>>work on. But it doesn't mean you lower the bar on your project.
>>
>>
>
>I'd have to disagree on this one. I'm all for documentation, etc...
>matter of fact I agreed with most of your other thoughts... but there
>are two (at least) different 'levels' of documentation. Pure "user
>level" documentation is not usually well written by the person(s) who
>wrote the code. But then again, I wouldn't want the person who can write
>good user documentation to write the javadocs, either...
>
>
>
You are talking about the difference between an author and an editor to
some degree. A developer has to document, and that includes being able
to impart in some form user level documentation if it pertains to what
they worked on, even if someone else reshapes that into something
prettier for general consumption. If the developer is unable to
effectively communicate their contribution, then that is not an issue
which should alter the project approach; it is an issue which should
alter whether that developer contributes or not. I find it personally
hilarious that we place as a prerequiste for a developer fluency in the
language of Java or C++ and completely discard fluency in the language
of English. Communication isn't some kind of optional "nice to have";
its a necessity.
Brad
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brad O'Hearne wrote:
<snip/>
>> And fourthly, the developers are often *not* the best people to write
>> the documentation. For someone who knows all the details of an
>> implementation it's quite hard to step back and write good introductory
>> tutorials.
>>
>>
> Absolutely they are. Especially in open source, they are the ones who
> know how something works, and is supposed to work. You cannot have
> someone who doesn't understand the product document it. What you are
> referring to is the inability of many developers to communicate concepts
> effectively, which is an entirely different issue. If a developer can't
> communicate their thoughts, well then, that's something they need to
> work on. But it doesn't mean you lower the bar on your project.
I'd have to disagree on this one. I'm all for documentation, etc...
matter of fact I agreed with most of your other thoughts... but there
are two (at least) different 'levels' of documentation. Pure "user
level" documentation is not usually well written by the person(s) who
wrote the code. But then again, I wouldn't want the person who can write
good user documentation to write the javadocs, either...
<snip/>
>
>> Just about every successful commercial product ever released has had
>> books about it published *months to years* after the product was
>> released. MS-Office tutoruals, RedHat administration guides, Hibernate
>> "developers notebooks". Continuing the documentation process after the
>> product is released is *normal*.
>>
>>
> Not analog. Because other projects were bad, doesn't mean you should
> aspire to the lowest common denominiator. Because there's a bum drinking
> a 40 oz of Colt 45 out of a paper bag down the street doesn't mean
> that's a good reason for all of us to do it.
Okay... so I guess I missed the point here - when IS a good reason for
all of us to do it? :-)
Seriously I don't think the issue is that people are saying "they did it
this way so that's the way we do it". Docs are good. Don't delay a
release because there isn't any - just write it as part of the release
cycle and there'll be no delay necessary. And putting my Jira where my
mouth is, I've already headed over there to see what I can do to help
(since I feel bad now having my Colt 45 wrapped in a paper bag out on
the desk :-D)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDQujaCoPKRow/gARAjbsAJ4yNKnp7bNd2o1ANoEbEddtyaQS9gCfd5uT
rdTEbUw3FZbgUsF1roFJ3qw=
=T1OT
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Brad O'Hearne <br...@neurofire.com>.
I'd like to reply to comments made by several posters:
>First of all, non-funded open-source projects (which is what this is)
>are usually done because someone needs a tool *themselves*. That person
>clearly does *not* need documentation.
>
The truth is, *every* project, your own private projects, or someone
else's *needs* documentation. Its just fine if you don't do it on your
private projects, because you aren't affecting anyone else. But as soon
as you bring up a community around it, ask for contributors, etc., it
becomes a shared, formal project. As soon as that project is shared, the
knowledge of its usage needs to be shared. Documentation is non-negotiable.
>If *you* need documentation,
>that's not the problem of the person writing the software.
>
It absolutely is. They have the knowledge. They know how it works --
moreover, they know how it is *supposed* to work. Another party cannot
account for that.
>In practice
>developers do write some documentation themselves; in some cases the
>documentation is very good. However it's not something that a user
>community can *demand* of the unpaid creators of a tool. And neither can
>we users demand that the developers delay releasing functionality they
>want because they haven't documented it enough for us to use.
>
>
First off -- this isn't about economics, its about the pursuit of
excellence in development, and doing a project right. If someone wants
to share a project, and invite my cooperation, feedback, and submitting
of code, which I have already in my first month of using it, then I see
no problem whatsoever in requesting that the project provide
documentation commensurate with the level of feature.
>Secondly, this is open source. If you really want to know how a
>particular piece works, read the code. It's the final and official
>documentation. Nothing is being hidden from any user of the software.
>
>
This statement right here summarizes everything that's wrong with the
attitude surrounding open source. The point of open source is not to
trade the time you would have developed something on your own with time
instead going on an easter egg hunt trying to figure out how something
works. You turn everyone into a developer that way, and you burn
everyone's time that they either could have been writing their own
custom solution which would meet all their own needs, or time they could
have been contributing to the project and making it better. Having to
tinker, dig, and read source code just to figure out how to use
something is just trading development time for Google time -- and you
end up paying big money either way.
There is one reason and one reason only for no or poor documentation on
any product, commercial or not: laziness. Neglect, that's it.
>Thirdly, documentation is *never* complete. There's always someone who
>
>
Not a reason not to document, and anyway, it isn't true. Documentation
can be as complete as the code. There's no magic to that.
>And fourthly, the developers are often *not* the best people to write
>the documentation. For someone who knows all the details of an
>implementation it's quite hard to step back and write good introductory
>tutorials.
>
>
Absolutely they are. Especially in open source, they are the ones who
know how something works, and is supposed to work. You cannot have
someone who doesn't understand the product document it. What you are
referring to is the inability of many developers to communicate concepts
effectively, which is an entirely different issue. If a developer can't
communicate their thoughts, well then, that's something they need to
work on. But it doesn't mean you lower the bar on your project.
>Just about every successful commercial product ever released has had
>books about it published *months to years* after the product was
>released. MS-Office tutoruals, RedHat administration guides, Hibernate
>"developers notebooks". Continuing the documentation process after the
>product is released is *normal*.
>
>
Not analog. Because other projects were bad, doesn't mean you should
aspire to the lowest common denominiator. Because there's a bum drinking
a 40 oz of Colt 45 out of a paper bag down the street doesn't mean
that's a good reason for all of us to do it.
>The most important piece is the first, though. As users we shouldn't
>demand but instead contribute. Updating the main site directly isn't
>possible, but improving documentation via a wiki is.
>
>
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. The web site doesn't even come close to
describing things to the point where someone could follow up with
documentation. 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. As it is, I'm about
a gnat's eyebrow away from writing my own custom alternative to maven.
It doesn't compute -- for the great product maven is, the lack of
documentation has turned the experience into a huge time pit. Every
problem is a new plugin and a new configuration option or file and a new
frontier of undocumented stuff, and a whole new cycle of trial and error.
Please understand that my comments are not directed at any person, they
are directed at an attitude I have seen perpetuated throughout my
career, which is negative. Let's call it what it is -- the lack of
documentation is just cutting corners. Its trading away completeness,
and excellence in a project for what is fun, and/or what we aren't
willing to wait for. The idea that because something is free, or
open-source, that it suddenly becomes this new entity that no one needs
an instruction manual for is just ridiculous. Its all just a piece of
software. And as a comment on a completely different issue, if
developers are going to discard the responsibiility to communicate their
thoughts, ideas, and designs well, you can say goodbye to your jobs,
because you've just severely commoditized whatever you have to offer as
a developer by eliminating the primary reason not to send your job
overseas (effective communication).
Whatever is worth doing, is worth doing well.
Brad
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Rinku wrote:
>
>>> *sigh* yeah... [been trying that approach - not w/ maven (yet) - and
>>> met with limited success because of "that's documentation. we're here to
>>> work on code" responses (or complete lack of response entirely) - hence
>>> my ire over "have users just look at the code" opinions.]
>>>
>>
>> Nah, I think that's a last resort. Because then we'd need to document
>> the code :)
>>
>>
>>> This is possibly the best thing I've ever heard said about a wiki.
>>> Taking knowledge from a wiki into documentation is great. Using a wiki
>>> AS documentation is where my issue arises.
>>>
> Documenting the code isn't a bad idea at all and can save *a lot* of
> pain for users who can't find answers on the list or docs as well as for
> contributors who want to work on patches.
>
> IMHO and from my humble experience it doesn't take long to to put a
> couple of lines of brief description of intent on methods and notes for
> complex code segments - especially when your brain is taking a few
> moments and running similar thought cycles and creating logical steps!
>
> of course, documenting an existing non-doc'ed code base could be scary ;-)
>
> +1 for code docs.
lol - +1 for code docs (although I believe that was more tongue and
cheek than anything) and a definite +1 to scary.
I don't think anyone was knocking the importance of docs - just the
when, by whom, at what level, and of what importance are they in
relation to the code and a release. As with everything else, opinions
vary and so does mileage.
>
> Rahul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDQkAaCoPKRow/gARAjKLAKCV+OnF1ztUbbTEpf+FdR2Kzxc5ZwCfad4+
vhDvIGE7dBggWmwYYmZIsrs=
=Pv8S
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by Rinku <ra...@gmail.com>.
>> *sigh* yeah... [been trying that approach - not w/ maven (yet) - and
>> met with limited success because of "that's documentation. we're here to
>> work on code" responses (or complete lack of response entirely) - hence
>> my ire over "have users just look at the code" opinions.]
>>
>
> Nah, I think that's a last resort. Because then we'd need to document
> the code :)
>
>
>> This is possibly the best thing I've ever heard said about a wiki.
>> Taking knowledge from a wiki into documentation is great. Using a wiki
>> AS documentation is where my issue arises.
>>
Documenting the code isn't a bad idea at all and can save *a lot* of
pain for users who can't find answers on the list or docs as well as for
contributors who want to work on patches.
IMHO and from my humble experience it doesn't take long to to put a
couple of lines of brief description of intent on methods and notes for
complex code segments - especially when your brain is taking a few
moments and running similar thought cycles and creating logical steps!
of course, documenting an existing non-doc'ed code base could be scary ;-)
+1 for code docs.
Rahul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> Agreed. However, the barrier to entry is actually quite high in this
> regard from personal experience on open source projects that place
> documentation below everything else. Contributions only go so far when
> made by a non-committer.
Yep, this is what I meant by this bit below, and also why I
highlighted that there are other ways to contribute.
> > Now, we do know there are missing pieces of documentation, and are
> > correcting that over time. It's also my personal vendatta to write
> > docs for new functionality at least going forward, and even if they
> > are brief so that people can expand on them easily.
I don't know why I called it a vendetta, its more of an ambition :)
> No offense intended here. I've seen the "give us documentation" and the
> "we know - we're working on it" threads. My hat's off to all the work
> that's been done.
None taken, it was a general comment.
> *sigh* yeah... [been trying that approach - not w/ maven (yet) - and
> met with limited success because of "that's documentation. we're here to
> work on code" responses (or complete lack of response entirely) - hence
> my ire over "have users just look at the code" opinions.]
Nah, I think that's a last resort. Because then we'd need to document
the code :)
> This is possibly the best thing I've ever heard said about a wiki.
> Taking knowledge from a wiki into documentation is great. Using a wiki
> AS documentation is where my issue arises.
:)
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Comments inline - and as a preface, they are directed from experience
outside (but not too far outside) of the Maven project itself.
Brett Porter wrote:
> I tihnk you both make pretty good points on this, even where you might
> agree to disagree. Unfortunately I don't have time to reply to this
> entire thread, but I couldn't resist this point:
>
> On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
>>> And fourthly, the developers are often *not* the best people to write
>>> the documentation. For someone who knows all the details of an
>>> implementation it's quite hard to step back and write good introductory
>>> tutorials.
>> On a roll here - although I'd replace "often" with "definitely". What
>> would be truly beneficial would be to have someone IN CHARGE (as much as
>> certain people are "IN CHARGE" of certain parts of the code) of
>> providing USER documentation for each release. A developer? Sure. But
>> NOT a core developer that "just knows".
>
> All you are talking about here is a contributing user. There is
> nothing stopping any user making that transition, and it would be
> welcomed - in fact, the minute we find one we'll hold on and never let
> go. It's rare for people to only contribute to documentation, and the
> couple who have volunteered to do so in the past have either ended up
> preferring to code or getting burned out on it very quickly.
Agreed. However, the barrier to entry is actually quite high in this
regard from personal experience on open source projects that place
documentation below everything else. Contributions only go so far when
made by a non-committer.
>
> By the way, in our projects, its rare for anyone to be in charge for
> anything code or documentation. The whole project is responsible for
> everything, and people do what they have to for their work or itches
> as time allows. As a project, we try and direct people with the
> capacity to the right areas.
In my usage of "in charge", I wasn't meaning _in charge_, more the
"person who specialized in..." - and there are always those.
>
> Now, we do know there are missing pieces of documentation, and are
> correcting that over time. It's also my personal vendatta to write
> docs for new functionality at least going forward, and even if they
> are brief so that people can expand on them easily.
>
> The key point of this all was that it is impossible for developers to
> know exactly where the holes are now. Rants about documentation are
> not going to change anything - *we already know* it needs work, and
> always will need work, as you've both said.
No offense intended here. I've seen the "give us documentation" and the
"we know - we're working on it" threads. My hat's off to all the work
that's been done.
>
> But there are many ways you can contribute:
> * file a bug for specific documentation problems. Even if you don't
> know the answer, say what you couldn't find or couldn't understand.
> * pick up a bug and research that single topic and write a doc for it.
> * put together outlines for other people to flesh out.
*sigh* yeah... [been trying that approach - not w/ maven (yet) - and
met with limited success because of "that's documentation. we're here to
work on code" responses (or complete lack of response entirely) - hence
my ire over "have users just look at the code" opinions.]
>
> As for the wiki, we consider that a workspace. Please use it if you
> can, and suggest ways to integrate it into the site if you find uesful
> things there. Patches are best - APT is no harder to write than wiki
> markup.
This is possibly the best thing I've ever heard said about a wiki.
Taking knowledge from a wiki into documentation is great. Using a wiki
AS documentation is where my issue arises.
>
> Thanks for your concern!
>
> - Brett
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDP5paCoPKRow/gARAhnpAKCLGpAvAGEROgkBX7WdnfUNPxoNzwCgxt5X
z2WVcKUQ9JmZ+xf+K8PrPYY=
=gjI9
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies in your
jar)
Posted by David Sag <ds...@epo.org>.
I heard about a very interesting way to attack this problem a couple of
years ago in the Cocoon project. At one of the big cocoon user/dveleoper
conferences (it could even have been at an apachecon) a small room of
people with varying degrees of familiarity with the source code worked
collaborativly for a stretch of about 6 hours to clean up the top 100
issues facing cocoon, including tons of documentation.
The proceedure was very simple but needs some tools.
Ingredients:
- 1 projector to display the list of issues for all to see
- some developers with commit rights
- 5 x that many other people willing to collaborate
- everyone needs an apple mac and SubEthaEdit (collaborative text editor)
and iChat.
method
- small teams (max 6 including the key-dev ala the dinner party principle)
rally about a developer with commit rights - the key-dev as i shall call
her - and choose an issue to address.
- key-dev opens master copy of code in SEE and other developers connect to
that via bonjour.
- everyone makes changes / be they code, javadocs, useage docs or
whatever.
- using ichat's status indicators to show others if you are still working
or done with your specific changes.
- when all done key-dev saves / builds / tests etc
- fix any new issues that have emerged from this cycle
- when done key-dev commits to SVN and the team is free to disband and
form a new team, or just keep on going with another issue.
I use the term swarm development to describe this approach and after
hearing about it from an apache mate we tried it within my old workplace
where many of the developers used macs. it was quite astounding how
quickly issues, especially documentation issues were nailed.
My suggestion is to coordinate a maven users / developers conference
somwhere where the weather is nice (I hear the April sun in Cuba is nice)
and we all collaboratively fix as many of the outstanding documentation
issues as we can.
iChat and SEE work over the wider internet too but there's nothing quite
like having a bunch of people in a single room attacking a set of problems
at once. the vibe is intense.
Kind regards,
Dave Sag
"Brett Porter" <br...@gmail.com> wrote on 07-03-2006 04:14:18:
> I tihnk you both make pretty good points on this, even where you might
> agree to disagree. Unfortunately I don't have time to reply to this
> entire thread, but I couldn't resist this point:
>
> On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> > >
> > > And fourthly, the developers are often *not* the best people to
write
> > > the documentation. For someone who knows all the details of an
> > > implementation it's quite hard to step back and write good
introductory
> > > tutorials.
> >
> > On a roll here - although I'd replace "often" with "definitely". What
> > would be truly beneficial would be to have someone IN CHARGE (as much
as
> > certain people are "IN CHARGE" of certain parts of the code) of
> > providing USER documentation for each release. A developer? Sure. But
> > NOT a core developer that "just knows".
>
> All you are talking about here is a contributing user. There is
> nothing stopping any user making that transition, and it would be
> welcomed - in fact, the minute we find one we'll hold on and never let
> go. It's rare for people to only contribute to documentation, and the
> couple who have volunteered to do so in the past have either ended up
> preferring to code or getting burned out on it very quickly.
>
> By the way, in our projects, its rare for anyone to be in charge for
> anything code or documentation. The whole project is responsible for
> everything, and people do what they have to for their work or itches
> as time allows. As a project, we try and direct people with the
> capacity to the right areas.
>
> Now, we do know there are missing pieces of documentation, and are
> correcting that over time. It's also my personal vendatta to write
> docs for new functionality at least going forward, and even if they
> are brief so that people can expand on them easily.
>
> The key point of this all was that it is impossible for developers to
> know exactly where the holes are now. Rants about documentation are
> not going to change anything - *we already know* it needs work, and
> always will need work, as you've both said.
>
> But there are many ways you can contribute:
> * file a bug for specific documentation problems. Even if you don't
> know the answer, say what you couldn't find or couldn't understand.
> * pick up a bug and research that single topic and write a doc for it.
> * put together outlines for other people to flesh out.
>
> As for the wiki, we consider that a workspace. Please use it if you
> can, and suggest ways to integrate it into the site if you find uesful
> things there. Patches are best - APT is no harder to write than wiki
> markup.
>
> Thanks for your concern!
>
> - Brett
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
Re: Maven documentation (was Re: how to include all dependencies in your jar)
Posted by Brett Porter <br...@gmail.com>.
I tihnk you both make pretty good points on this, even where you might
agree to disagree. Unfortunately I don't have time to reply to this
entire thread, but I couldn't resist this point:
On 3/7/06, Brian K. Wallace <br...@transmorphix.com> wrote:
> >
> > And fourthly, the developers are often *not* the best people to write
> > the documentation. For someone who knows all the details of an
> > implementation it's quite hard to step back and write good introductory
> > tutorials.
>
> On a roll here - although I'd replace "often" with "definitely". What
> would be truly beneficial would be to have someone IN CHARGE (as much as
> certain people are "IN CHARGE" of certain parts of the code) of
> providing USER documentation for each release. A developer? Sure. But
> NOT a core developer that "just knows".
All you are talking about here is a contributing user. There is
nothing stopping any user making that transition, and it would be
welcomed - in fact, the minute we find one we'll hold on and never let
go. It's rare for people to only contribute to documentation, and the
couple who have volunteered to do so in the past have either ended up
preferring to code or getting burned out on it very quickly.
By the way, in our projects, its rare for anyone to be in charge for
anything code or documentation. The whole project is responsible for
everything, and people do what they have to for their work or itches
as time allows. As a project, we try and direct people with the
capacity to the right areas.
Now, we do know there are missing pieces of documentation, and are
correcting that over time. It's also my personal vendatta to write
docs for new functionality at least going forward, and even if they
are brief so that people can expand on them easily.
The key point of this all was that it is impossible for developers to
know exactly where the holes are now. Rants about documentation are
not going to change anything - *we already know* it needs work, and
always will need work, as you've both said.
But there are many ways you can contribute:
* file a bug for specific documentation problems. Even if you don't
know the answer, say what you couldn't find or couldn't understand.
* pick up a bug and research that single topic and write a doc for it.
* put together outlines for other people to flesh out.
As for the wiki, we consider that a workspace. Please use it if you
can, and suggest ways to integrate it into the site if you find uesful
things there. Patches are best - APT is no harder to write than wiki
markup.
Thanks for your concern!
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven documentation (was Re: how to include all dependencies
in your jar)
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
I try to keep my mouth shut about this as much as I can, but when you
take a stance as definite as this... [entirely focusing on
'documentation' outside the realm of the original issue]
Simon Kitching wrote:
> I don't agree at all.
>
> First of all, non-funded open-source projects (which is what this is)
> are usually done because someone needs a tool *themselves*. That person
> clearly does *not* need documentation. If *you* need documentation,
> that's not the problem of the person writing the software. In practice
> developers do write some documentation themselves; in some cases the
> documentation is very good. However it's not something that a user
> community can *demand* of the unpaid creators of a tool. And neither can
> we users demand that the developers delay releasing functionality they
> want because they haven't documented it enough for us to use.
My take on "non-funded open-source projects" is that they are *not* done
because someone needs a tool. They are done because someone needs a tool
AND wants to let "the world" take part in developing and using - it. If
it were just because someone needed a tool, you'd look to your hard
drive and find all those tools you have developed over the years - most
if not all with no documentation. The second it becomes a "project",
documentation goes with it. To state that a USER community cannot
"demand" (hoping "demand" here is used more as "feels there should be",
not "Developers! Write user documentation or else!") user documentation
is utterly ridiculous. Projects rise and fall based on user
documentation. Not all, maybe not most - but the more complex the
project is, the more likely it becomes that user documentation is a
"must have" for success outside the core developers of it. Should
functionality be delayed for it? Not always - but sometimes, yes. Write
a little documentation on how to use it and developers won't have to
spend as much time answering the same questions on the mailing list.
Ounce of prevention and all that.
>
> Secondly, this is open source. If you really want to know how a
> particular piece works, read the code. It's the final and official
> documentation. Nothing is being hidden from any user of the software.
This always strikes me as an "open source" oddity. If there's ever a
question about "open source", the answer "read the code" always pops up.
What I fail to understand is why, although someone may be a developer -
a Java developer - and possibly a very good one, they are naturally "in
tune" with a project, its coding styles, how it works and where to go in
the code to fix something. This is where "the user is a developer"
doesn't mesh. Just being a developer doesn't mean you're a maven/<insert
project> developer. Therefore, wanting to USE a piece of software should
mean being able to USE it without going to code to see how.
That said... True statement. Nothing is being hidden.
>
> Thirdly, documentation is *never* complete. There's always someone who
> doesn't understand a topic, or who wants to do something out of the
> ordinary. I'd consider your request to package dependencies of a module
> inside the jarfile as an example of that. It would be frustrating to see
> new functionality kept unreleased because *some* of the potential users
> are not able to understand it or want to use it in unexpected ways.
I couldn't agree more.
>
> And fourthly, the developers are often *not* the best people to write
> the documentation. For someone who knows all the details of an
> implementation it's quite hard to step back and write good introductory
> tutorials.
On a roll here - although I'd replace "often" with "definitely". What
would be truly beneficial would be to have someone IN CHARGE (as much as
certain people are "IN CHARGE" of certain parts of the code) of
providing USER documentation for each release. A developer? Sure. But
NOT a core developer that "just knows".
>
> Just about every successful commercial product ever released has had
> books about it published *months to years* after the product was
> released. MS-Office tutoruals, RedHat administration guides, Hibernate
> "developers notebooks". Continuing the documentation process after the
> product is released is *normal*.
Okay. Off that roll we were on. Although I agree with everything here,
the implication is that there isn't USER documentation until afterward.
Tutorials, How-To's, advanced user documentation? Sure. The sooner the
better, yes. But documentation evolves as much (coincidentally
sometimes) as the code. The key to successful usage of a project,
however, is the user's ability to *cough* USE it. Having Hibernate in
there struck me as their documentation has been pretty good from the
beginning - FOR USERS. Don't as me to go in to developer documentation
as I'm not, nor have I any interest in becoming, a Hibernate developer.
[another good example of USER documentation would be Spring].
>
> The most important piece is the first, though. As users we shouldn't
> demand but instead contribute. Updating the main site directly isn't
> possible, but improving documentation via a wiki is.
Agreed. Users *should* contribute what they can. But I'd give a mint to
the guy that destroyed the Wiki's ability to function as true
"documentation".
>
> Regards,
>
> Simon
Brian
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFEDPVtaCoPKRow/gARAj1MAKCFwTSlcwaC/nbvqRSTXyXEMpq+dwCgv4j8
vwm4LpyE09hbrrTqcZM34ak=
=oS7o
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org