On Mon, 16 Dec 2002, Vladimir R. Bossicard wrote: > Hi Joan, > > Just a quick review: > > - you should maybe target the users (like in the Tomcat howto) and not > the developers. Developers can normally use users' how-tos, but the > opposite is often not true. >
i used the tomcat howto as a template (e.g. intended audience). i was trying to make the doc as simple yet complete as possible (hence 'soup-to-nuts' in title). my thinking was that a user doing a jetty config will need to have enough skills to run the basic commands used in the examples. please let me know parts you think would be too difficult for a user (or feel free to change the doc) > - describing how to install Jetty is the role of the Jetty folks, not > ours. Just point the user to where he/she can find the adequate > information. > that's fine. i guess i have a pet peeve about 'howto' docs that refer to other sites/dox for 'howto' instructions...particularly since this was meant to be a basic soup-to-nuts howto for ... us all this is a matter of style which, well, i might as well hand over my 2 cents on: 1) i have gotten the most usefulness from some of the off-site howto's (like t. dyson's), that give complete step-by-step instructions & suggestions (these sites would probably not exist if the need was filled 'at home') 2) i had real trouble trying to build & configure jetty using the jetty doc. others have said the same about compiling tomcat from source ... as i mentioned, i tried this several ways (resulting in several migraines), and this is what prompted me to write a soup-to-nuts howto - so other could avoid unnecessary headaches ... probably why tom wrote his too 3) i think the only steps i give are to download the binary, set the environment variable, and verify the install... this much is implied in other howto's (step: echo $JAVA_HOME to verify JDK install) 4) if there are other xindice users like me, they will not ever have installed tomcat/jetty before (and may not have any other need for 'containers'). the key is that it is not necessary to write a $JETTY_HOME/etc/xindiceN.NA.xml file, as jetty vanilla howto might suggest ... just trying to skip to the punch hoo. that was 2 cents? again feel free to cut/edit the doc, particularly if you feel that the info is extraneous > - How to build Xindice is described in another document (compilation > how-to). In general, we should avoid duplicating information at all > cost (risk of not synchronized docs). > i haven't seen any how-to about fixing up the system.xml file. i may have missed some dox/discussions, but the last work i heard was inconclusive about how/where/when the xindice db path would be established... it simply won't work to try to run jetty from xindiceN.NA.war (because the db path is relative, and it is archived in the war) this is why i ask for reviewer feedback on this point ... this is also a different way of configuring the build (which would, in fact, be more appropriate to include in the CVS build.xml - i made reference to this in the e-mail). for this reason, it seems appropriate to *include* the Xindice build step - because it is not the 'vanilla' build... > - explaining how to use Forrest with Jetty should go into the > "contributing to the documentation" how-to in the dev section. > this is actually not explaining how to use forrest w jetty (since jetty is now embedded in forrest, one only has to type 'forrest run'), rather it is a final step to get and use forrest (w - btw - it's own embedded jetty) to peruse Xindice CVS dox. whether or not the user actually writes and contributes doc is optional:-) is the forrest-formatted doc only a cvs thing (i.e. will the gold release have .html or .xml doc)? since the CVS doc is always a delta (or 2 or 3..) away from the public web site, i think that everyone (not just doc contributors) should be instructed on how to use forrest to access the CVS dox. it can't get much simpler than the 3 steps listed there if this is yet another 'howto' ... well, i did my best... > hth > > -Vladimir > > -- > Vladimir R. Bossicard > Apache Xindice - http://xml.apache.org/xindice > let me know how you want to go about updates. i think you have a better idea than i of the doc structure you'd like to achieve. at some point there may be other feedback from those brave people who actually use forrest to review xindice dox (brave people: we're waiting by our mailboxes!) i think that if i update the doc now to fulfill the spirit of the review comments, there will be very little 'howto' left in it ... you? thanks for your feedback. did the steps work for you?
