Ken, I'm all for quality - but at the moment perhaps the more important thing is _some useful_ documentation, rather than world best practice?
Personally I'm happy with a bunch of linked HTML files that look OK and are readable - but most of all - have good content! :) Anyone else? -mike On 12/12/02 11:11 PM, "Ken Egervari [eXtremePHP]" ([EMAIL PROTECTED]) penned the words: > Hani, > > That's pretty much my opinion about Maven and Cocoon (minus all the > antagonism towards Jakarta and related OSS projects :P). > > > > I want to build something simple, but I also want to have the flexibility to > do the 3 things we need: HTML (for local use), JSP (as currently being used) > and PDF. In the case of PDF, the actual generated document should be very > different than the html version, but in some of the projects I've look at, > they have degenerated the content of a PDF file to be as low as a simple > ASCII document with a few uses of text styles and colours. In my view, this > isnıt a powerful utilize PDF documents since it would probably be productive > and efficient to use plan ASCII then. > > > > To get the desired quality for our documentation, we need to use different > tools rather than a generic tool that is less powerful. I mean, the only > thing that relates HTML to PDF is the content itself. However, the way the > content is organized, its presentation, the usability issues, etc. are > completely different when you compare PDF to HTML. A generic tool doesnıt > really play to the strengths of either. > > > > This is why I considered hand-written XSLT documents and a simple Java > program to make PDF documents. I figured it was important to make qualityı > documentation rather than easy-to-generateı documentationı. > > > > This approach is still very simple. It doesnıt rely on any complex > frameworks. The main principle for our documentation should be: ³it only > generates documentation and it does it well². Personally, I really like > this approach despite some of the upfront work to make it happen. I had a > lot of ideas as to how the PDF document was going to look and iText/SAX (or > some higher level xdoc library) seemed like a pretty way to make quality and > customized documentation. > > > > Of course, this is up to debate and if Iım wrong here, thatıs okay too. I > just want to do the best possible work for the project. Thatıs really what > this is all about :) Suggestions are always welcome. > > > > Regards, > > Ken Egervari > > > ----- Original Message ----- > From: "Hani Suleiman" <[EMAIL PROTECTED]> > To: <[EMAIL PROTECTED]> > Sent: Thursday, December 12, 2002 6: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 ------------------------------------------------------- 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
