I think the docs should be a Word 2000 file. Or a PDF! On Tue, 10 Dec 2002, Hani Suleiman wrote:
> I think that html for documentation is FAR superior to having jsp files or > anything that requires some sort of specialised server. The jsp files assume > you've managed to build and install webwork, when logically, the instructions to > do so would be part of the very docs you're trying to install! > > So my vote goes to having documentation that can be accessed out of the box. It > shouldn't require anything other than a browser that you can point at some local > file. > > Quoting "Ken Egervari [eXtremePHP]" <[EMAIL PROTECTED]>: > > > Pat, > > You think it's overkill? I rather like the simplicty of XML. I also have > > used XSLT in many solutions already and I wrote about too in one of my > > books. Needless to say, I'm really confortable with it. > > > > XSLT will also help us out if the website presentation layer changes or > > when > > we decide to compile the manual into a PDF document (which I really hope we > > do since PDF is a fantastic format for printing and offline viewing). XML > > will critical to achieve this. > > > > Besides, I'll be the one to maintain it so everyone else will simply see > > the > > plain old HTML documents and technical be ignorant of the XML. > > > > I have noticed that the current documentation uses JSPs, but I really would > > like to change that. I think a similar OS product (Sitemesh maybe?) had > > the > > manual itself use Sitemesh. This was a problem for me since it doesn't > > work > > on JBoss (using JBossWeb). So if you wanted to read the manual for > > installation instructions or types on how to fix this problem, you couldn't > > easily get at that information without uncompressing the war and reading > > the > > files manually. This isn't desirable when trying to get a product to work. > > A lot of people would probably just give up. > > > > If you still think XML is a poor format to use given these cases, then I'll > > write them up in HTML. However, I think we'll be missing out on some key > > advantages while I don't see any inherit problems with using XML (except > > for > > many it'll take a little longer to setup, but this won't be a problem). > > Please let me know your thoughts. > > > > Ken > > > > ----- Original Message ----- > > From: "Patrick Lightbody" <[EMAIL PROTECTED]> > > To: <[EMAIL PROTECTED]> > > Sent: Tuesday, December 10, 2002 10:23 AM > > Subject: Re: [OS-webwork] Documentation > > > > > > > Ken, > > > I tend to prefer simple HTML documentation. XML -> XSLT -> HTML is > > overkill. > > > I nice batch of HTML files should suite us well. > > > > > > -Pat > > > > > > ----- Original Message ----- > > > From: "Ken Egervari [eXtremePHP]" <[EMAIL PROTECTED]> > > > To: <[EMAIL PROTECTED]> > > > Sent: Tuesday, December 10, 2002 12:06 AM > > > Subject: Re: [OS-webwork] Documentation > > > > > > > > > > Everyone, > > > > > > > > Actually, what I actually wanted to do was combine all the forms of > > > > documentation written by various people and consolidate it into a book > > > > fashion. That way it will be very easy for someone to download a PDF > > file > > > > or have the documentation html on their local machine. > > > > > > > > I for one never knew the 'WebWork Cookbook' existed unto boxed pointed > > it > > > > out to me. I think many others probably missed this great resource as > > > well. > > > > I truly think the goal here is make the product documentation a single > > > unit > > > > that is comprehensive, practical and easily accessible. If we can do > > > that, > > > > I think WebWork will be find it's way into more projects and will be a > > > > better competitor to Struts. > > > > > > > > I had talked to boxed about storing the documentation in XML and using > > > > various style sheets and/or parsers to make various forms of the > > > > documentation (like PDF and static HTML). Currently, the easiest form > > of > > > > documentation is by directly using the OS website, but sometimes that's > > > not > > > > convenient if you don't have an Internet connection available or want > > to > > > > learn more about WebWork on your laptop during a long train ride. > > > > > > > > Even further, if the documentation is updated on the server, users > > won't > > > > have access to older versions of that documentation (for their > > respective > > > > version). This way, we can version our documentation with the product > > > > releases better. I'm sure many people will enjoy this benefit for > > > projects > > > > already in production. > > > > > > > > Please let me know if you agree with these comments and your thoughts > > > about > > > > executing them. I have my own ideas about these plans, but with > > > > collaboration from all people involved, I'm sure we can make this work > > > > effectively. I look forward to spearheading these plans and I know > > they > > > > would help WebWork in many ways. > > > > > > > > Regards, > > > > Ken Egervari > > > > > > > > ----- Original Message ----- > > > > From: "Mike Cannon-Brookes" <[EMAIL PROTECTED]> > > > > To: <[EMAIL PROTECTED]> > > > > Sent: Monday, December 09, 2002 11:34 PM > > > > Subject: Re: [OS-webwork] Documentation > > > > > > > > > > > > > Toby, > > > > > > > > > > Great stuff - I've added a link to it from the WebWork page on the > > > wiki - > > > > > thanks! > > > > > > > > > > Cheers, > > > > > Mike > > > > > > > > > > On 10/12/02 2:40 PM, "Toby Hede" ([EMAIL PROTECTED]) > > penned > > > the > > > > > words: > > > > > > > > > > > Hi, > > > > > > > > > > > > I have been planning some documentation stuff as well, I started > > with > > > a > > > > > > dummies guide: > > > > > > > > > > > > http://info-architects.net/webwork/fundamentals-dummies.html > > > > > > > > > > > > And I need to get working on some other areas as well. > > > > > > > > > > > > Toby > > > > > > > > > > > > > > > > > > > > > > > >> Ken, > > > > > >> > > > > > >> Agreed - we greatfully appreciate any improvements to the > > > > documentation! > > > > > >> > > > > > >> Perhaps the best way you (or anyone - it's really easy!) can help > > out > > > > is > > > > > >> just to start documenting things on the Wiki > > > > > >> (http://www.opensymphony.com:8668). Anyone can sign up and write > > some > > > > > >> extra pages of information. > > > > > >> > > > > > >> This saves hassling with CVS, HTML, XML etc. > > > > > >> > > > > > >> Have a look at > > > http://www.opensymphony.com:8668/space/WebWork+CookBook > > > > > >> for examples of where people are just documenting on the fly - > > it's > > > > > >> quite refreshing! > > > > > >> > > > > > >> Welcome on board - if you need anything, just yell. > > > > > >> > > > > > >> Cheers, > > > > > >> Mike > > > > > >> > > > > > >> On 10/12/02 7:16 AM, "Wayland Chan" ([EMAIL PROTECTED]) penned the > > > > > >> words: > > > > > >> > > > > > >>> Welcome to the project and kudos on a very well > > > > > >>> written introduction of yourself. > > > > > >>> > > > > > >>> Looking *very* forward to your contributions. > > > > > >>> > > > > > >>> > > > > > >>> > > > > > >>> __________________________________________________ > > > > > >>> Do you Yahoo!? > > > > > >>> Yahoo! Mail Plus - Powerful. Affordable. Sign up now. > > > > > >>> http://mailplus.yahoo.com > > > > > >>> > > > > > >>> > > > > > >>> ------------------------------------------------------- > > > > > >>> This sf.net email is sponsored by:ThinkGeek > > > > > >>> Welcome to geek heaven. > > > > > >>> http://thinkgeek.com/sf > > > > > >>> _______________________________________________ > > > > > >>> Opensymphony-webwork mailing list > > > > > >>> [EMAIL PROTECTED] > > > > > >>> https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > >> > > > > > >> > > > > > >> > > > > > >> ------------------------------------------------------- > > > > > >> This sf.net email is sponsored by:ThinkGeek > > > > > >> Welcome to geek heaven. > > > > > >> http://thinkgeek.com/sf > > > > > >> _______________________________________________ > > > > > >> Opensymphony-webwork mailing list > > > > > >> [EMAIL PROTECTED] > > > > > >> https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > > > > > > > > --------------------------------------------- > > > > > > Technoshamanistic Resistance Within Hyper-Transgressive Ontology > > > > > > > > > > > > Me Blog: http://info-architects.net/terablog/ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > ------------------------------------------------------- > > > > > > This sf.net email is sponsored by:ThinkGeek > > > > > > Welcome to geek heaven. > > > > > > http://thinkgeek.com/sf > > > > > > _______________________________________________ > > > > > > Opensymphony-webwork mailing list > > > > > > [EMAIL PROTECTED] > > > > > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > > > > > > > > > > ------------------------------------------------------- > > > > > This sf.net email is sponsored by:ThinkGeek > > > > > Welcome to geek heaven. > > > > > http://thinkgeek.com/sf > > > > > _______________________________________________ > > > > > Opensymphony-webwork mailing list > > > > > [EMAIL PROTECTED] > > > > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > > > > > > > > > > > ------------------------------------------------------- > > > > This sf.net email is sponsored by:ThinkGeek > > > > Welcome to geek heaven. > > > > http://thinkgeek.com/sf > > > > _______________________________________________ > > > > Opensymphony-webwork mailing list > > > > [EMAIL PROTECTED] > > > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > > ------------------------------------------------------- > > > This sf.net email is sponsored by:ThinkGeek > > > Welcome to geek heaven. > > > http://thinkgeek.com/sf > > > _______________________________________________ > > > Opensymphony-webwork mailing list > > > [EMAIL PROTECTED] > > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > ------------------------------------------------------- > > This sf.net email is sponsored by:ThinkGeek > > Welcome to geek heaven. > > http://thinkgeek.com/sf > > _______________________________________________ > > Opensymphony-webwork mailing list > > [EMAIL PROTECTED] > > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > > > > > > > > > > > ------------------------------------------------------- > This sf.net email is sponsored by:ThinkGeek > Welcome to geek heaven. > http://thinkgeek.com/sf > _______________________________________________ > Opensymphony-webwork mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > --------------------------------------------------------- Joseph B. Ottinger [EMAIL PROTECTED] http://enigmastation.com IT Consultant ------------------------------------------------------- This sf.net email is sponsored by:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
