I really think we should look at the long term as the manual is a critical piece of WebWork like any part of the code. The documentation is really no different than refactoring code for instance - we refactor to improve the design of our system for the long term so that our code is more manageable. If this is important to do in our code, why would be do any less for the product's documentation? Doesn't the documentation have the same importance as the product itself? Your particular argument isn't very sound because we, as programmers, don't write the quick and fast solution for most code (especially frameworks) because we care about the quality and long term success (maintainability, reusability, traceability, etc.). Given this argument, I think using XML for documentation will be critical to WebWork's long term success.
----- Original Message ----- From: "Patrick Lightbody" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, December 10, 2002 12:01 PM 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-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 > > > > -- > > ---------------------------------- > > 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:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
