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
