Hani, I agree with you here. I haven't made up my mind if I like Maven of if I hate it, but I'm sure that whatever we end up doing, it'll be something that continues the goals of OpenSymphony and WebWork alike: simplicity.
-Pat ----- Original Message ----- From: "Hani Suleiman" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Thursday, December 12, 2002 3:52 AM Subject: Re: [OS-webwork] Documentation > I'm actually fairly strongly against maven. It's a huge project, and > almost all of the websites produced by it have a cookie cutter feel to > it. I also disagree with it being 'the way of the future'. It might be > a fashionable choice for many OSS projects, but so are a lot of other > things that have little beyond 'coolness' factor attached. > > I have no objections to xdocs, as it'd actually be a useful relevant > tool for the point at hand. Bringing in maven just to use xdocs though > is like buying a house with toolshed attached when all you wanted is a > screwdriver. > > It's not a case of 'not invented here', it's a case of 'not jumping off > the same lemming cliff that everyone else does, just because everyone > else is'. A severe example of this is xdoclet. It's a great tool, I use > it and rely on it completely. However, whenever I've tried working on > bits of it to improve/contribute, I throw my arms up and give up, > because it's so damn unwieldy. Having to installl maven just to read > the cvs docs makes me very suspicious. Heck, someone even thought it > necessary to internationalise the build messages! Featuritis gone mad, > from where I stand (sorry Aslak!). > > Webwork's beauty to me is precisely because I don't have to commit to > 20 other jars just to get trivial stuff to happen. While that too might > be 'the way of the future' (if you consider the future to be jakarta > projects + jakarta project wannabes), it'd be a sad day for webwork to > conform to that particular wave. > > I know this argument has come up before, and I hope this thread doesn't > degenerate into another flamefest (hilarious as I found the last one). > So please take my comments for what they are; a heartfelt plea from the > webwork user/occasional contributor gallery. > > On Thursday, December 12, 2002, at 06:03 AM, Mike Cannon-Brookes wrote: > > > Ken, > > > > You bring up a lot of interesting things here, I’ll try to reply below > > (note: I’m far from a documentation expert). > > > >> Well, I've been looking at a bunch of technologies that we can use to > >> build > >> the documentation, but I'm not convinced that Maven will help us. > >> Maven is an > >> interesting project in that it does a hundred different things, but > >> in terms > >> of simplicity and the information available on the website, it's not > >> there. I > >> think the documentation generation features are not nearly as > >> important in the > >> developer's minds in comparison to the project information, tools to > >> simplify > >> build/test cycles and all the other stuff it does. It also seems to > >> integrate > >> with Turbine and all these other frameworks that I didn't know exist. > >> I think > >> if people were worried about bloating this part of the project with a > >> tool > >> like Xalan, then they would definitely have some pretty strong > >> opinion to not > >> using Maven (I think I agree with them). Since we aren't using Maven > >> for it's > >> other strengths, it's kind of clumsy to start using it for > >> documentation now > >> when simpler solutions make more sense. > > > > I think people suggested Maven because it's 'the way of the future'. > > We have > > just started to use it at work, and it is fantastic once you get it > > running. > > As far as producing 'simple' documentation, it is very good. It uses > > xdoc > > from Apache, which would be my preferred way to generate the > > documentation > > (it's very simple, and 'mere mortals' can actually use it to write!). > > > >> I seriously think simple tools like Xalan are more than enough because > >> everyone probably has them in their classpath already, but I'm > >> looking into > >> Cocoon and Forrest right now (I'll put up another post to the > >> newsgroup about > >> my opinions on those) to see if they can simplify the required > >> plumbing. > > > > Cocoon and Forrest are huge overkill here I feel. > > > >> I'm much more interested in offline documentation generation where I > >> can > >> simply include the static documents, the PDF files and the source > >> code to > >> build all of that (rather than include the necessary targets in the > >> build.xml). It doesn't make much sense to have every person in > >> WebWork have > >> these documentation generation tools on their computer right now > >> since we > >> haven't rolled out the documentation yet. I would only include the > >> documentation generation code and jars into the build.xml when we have > >> something we are happy with. > > > > Well, I'm quite sure WebWork will end up using Maven after 1.3 (ie in > > the > > next few months), so using it to build documentation probably makes > > sense > > there. As for simplicity, it couldn't be easier to generate 'maven > > doc' :) > > > >> iText was another library I was thinking about using due to its > >> simplicity and > >> flexibility. I'd need to code a few Java classes to convert the xml > >> document > >> to PDF, but this wouldn't take more than a day. Again, I would only > >> do this > >> just so we wouldn't need a full-blown framework like Cocoon or > >> Forrest. Like > >> others have said, it's not a good idea to have Webwork developers or > >> the user > >> base that compiles from the source to be dependant on Cocoon or > >> Forrest and I > >> agree with that. I'd like to look into them anyway just so I know > >> for myself > >> how they work. If one of them will truly make our job much simpler > >> to the > >> point where I don't have to write a line of Java code, then I'll > >> consider > >> them. Otherwise, I don't see the point to use them. > > > > Gah! Let's not fall into the 'not invented here' syndrome, surely we > > don't > > need to write any tools to do this. > > > > This is why people suggested HTML, it's much _simpler_! :) > > > > The point is, surely the tools are an ancilliary issue? It's fairly > > trivial > > to move between tools at any time (half an hour of copy / paste at the > > most). Let's concentrate on the big issues! > > > >> Since the documentation is going to be static pages, I'll have to > >> redesign the > >> layout of the documentation obviously. This means that the left-side > >> will be > >> a little different to accommodate the documentation while I'll > >> probably keep > >> the top bar very similar. We also need to coordinate integrating > >> this on the > >> www.opensymphony.com <http://www.opensymphony.com> website as well > >> as it > >> won't use sitemesh or whatever other gadgets the site is using now. > >> These > >> issues aren't a huge rush, but we could begin to talk about them. > > > > Well, that's the beauty of SiteMesh - just drop the documentation in > > and it > > will be decorated automatically. The actual HTML produced should be > > _very_ > > simple, and use CSS to style everything. That way we can reuse it in > > many > > places. > > > > Again - concentrate on the bigger issues of writing it, adding / > > moving a > > logo is trivial! > > > > Good thoughts though all of them - it's great to have someone thinking > > about > > it. My advice, let's start simple and just get things down first - we > > can > > worry about the details of the layout / tools later? > > > > -mike > > > >> Regards, > >> Ken Egervari > >> > > > > > > > > > > ------------------------------------------------------- > > This sf.net email is sponsored by: > > With Great Power, Comes Great Responsibility > > Learn to use your power at OSDN's High Performance Computing Channel > > http://hpc.devchannel.org/ > > _______________________________________________ > > Opensymphony-webwork mailing list > > [EMAIL PROTECTED] > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > ------------------------------------------------------- > This sf.net email is sponsored by: > With Great Power, Comes Great Responsibility > Learn to use your power at OSDN's High Performance Computing Channel > http://hpc.devchannel.org/ > _______________________________________________ > Opensymphony-webwork mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork ------------------------------------------------------- This sf.net email is sponsored by: With Great Power, Comes Great Responsibility Learn to use your power at OSDN's High Performance Computing Channel http://hpc.devchannel.org/ _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
