Would something like www.xopus.org make this easier? You can edit the XML directly in a WYSIWYG editor rendered using the XSD you're planning to use for generating the HTML...
-----Original Message----- From: Patrick Lightbody [mailto:[EMAIL PROTECTED]] Sent: Tuesday, December 10, 2002 12:01 PM To: [EMAIL PROTECTED] Subject: Re: [OS-webwork] Documentation I found that writing docs in straight HTML (using Dreamweaver) is _much_ quicker than setting up (or using an existing, in the case of WW) XML DocBook installation and translation process. Basically, XML isn't intuitive when it comes down to it. It may be better suited in the long run, but for documents for Open Source projects where our time is limited, HTML proves to be the fastest (assuming you have a good GUI editor). -Pat ----- Original Message ----- From: "Bill Lynch" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, December 10, 2002 8:58 AM Subject: Re: [OS-webwork] Documentation > > 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! > > Agreed - but I'd vote for the docs being stored in XML. For > distributions they > should be transformed to HTML - that'd be the easiest way for people > to read > everything. > > Regards, > --Bill > > > 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-webw > >>>>>>>>ork > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>>------------------------------------------------------- > >>>>>>>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-webwo > >>>>>>>rk > >>>>>> > >>>>>> > >>>>>>--------------------------------------------- > >>>>>>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-webwor > >>>>>>k > >>>>> > >>>>> > >>>>> > >>>>>------------------------------------------------------- > >>>>>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 > > -- > ---------------------------------- > Bill Lynch, Jive Software > [EMAIL PROTECTED] > > > > ------------------------------------------------------- > 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: 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
