[OS-webwork] Documentation

[Ken Egervari [eXtremePHP]]

Hey guys,   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 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.    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.   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.   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 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.   Regards, Ken Egervari