Documentation is 100% the largest weakpoint of maven. On 9/24/07, Steve Mactaggart <[EMAIL PROTECTED]> wrote: > Case in point > http://maven.apache.org/guides/mini/guide-multi-module.html > > Something that is really useful, but still non existant. > Another datapoint: I've read both books, been using it daily since January, and still don't feel like I have a handle of how it all works.
Whatever tutorial information out there has to explain, at some level, of the steps & data maven uses to do what it does. In ant, it's simple: the tags describe the procedures used. In maven, so much of it is implicit (but un/under documented) that it's tough to see what's going on. A description of maven's internal procedures is needed -- to turn that black box white. There's no fundamental reason why maven can't be well documented. _Just tell us how the thing works_. >From that, you can describe how other things hook onto maven, and thusly how it and the plugins work. It's also a great way to entice developers to contribute, if they already have a working idea of how the system works internally. Also, some basic listing functionality of what maven takes in would be nice. Even if it's web based. I've found mvnrepository.org to be great, but that's something I found via googling. But how about something for archetypes? I've found something now and then through extensive googling, but this really should be on the 1st page of documentation for maven. As should a search box for mvnrepository. That's probably the best first test to use for the quality of maven's docs: how much can you figure out and use without having to hit google? Just using maven.apache.org, how functional is a new developer? Mailing lists are another thing I'd blacklist from this test. If someone has to ask about something on the mailing list, the documentation has failed. And while plugins having entire sites is nice, it'd be great if we could generate a reference manual (even if it's another HTML website) that covers every plugin that we're using in a project. If it's there, I haven't found it. This isn't to discourage the existing documentation efforts -- but prioritize documentation to be #1. I think for most users, maven's good enough by far, and a lot better than the competition. The advantages it gives are well worth it, _if_ they could figure out how to use it. -- H. Lally Singh Ph.D. Candidate, Computer Science Virginia Tech --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
