Ken, By all means - knock yourself out!
If you can write proper documentation for WebWork, everyone will love you no matter what technologies you use to write it ;) Cheers, Mike On 11/12/02 9:06 AM, "Ken Egervari [eXtremePHP]" ([EMAIL PROTECTED]) penned the words: > Hi Mike, > > To clarify, I was going to take the existing documentation and combine it > with all the work we already have in the WebWork Cookbook. Furthermore, I > was going to add-in a whole bunch of stuff to make it seem like a 'book' > with a single vision and style rather than seem like a set of different > works from various people. In a sense (like I said before), I think the > goal of the documentation should these 3 things: > > - Accessible: We should be able to use the documentation locally using any > browser with no app servers at all and that we should support formats like > PDF for offline viewing and printing as well. > - Comprehensive: The documentation will contain all our current knowledge > base and more as a 'single unit'. This also means that I would like to > increase the quality of the current documentation (documentation flow, > clarify concepts, fix technical and grammatical errors, etc.) as a whole and > provide more depth when necessary. > - Practical: The documentation should be useful to all WebWork developers > and should contain the information they expect no matter how trivial or > advanced. Again, a book-like fashion will help here and the integration of > the Cookbook material will also help. > > Also to clarify, I was more than willing to do this as a project by myself > mostly. As I said before, I'm an experienced author and I have no problems > helping out in these areas. I think if one person organizes the material to > his vision, this will improve the quality of the documentation greatly. > This doesn't mean other people are locked out of course (that would be > really dumb), but I'm sure you'll agree that many books written by 12+ > authors lack focus and quality while others that are written by a single > individual have much greater value. I think we should play to these > strengths as they have shown to be true time and again and this will be a > key factor in helping WebWork create more success. > > Regards, > Ken Egervari > > ----- Original Message ----- > From: "Mike Cannon-Brookes" <[EMAIL PROTECTED]> > To: "[EMAIL PROTECTED]" > <[EMAIL PROTECTED]> > Sent: Tuesday, December 10, 2002 4:31 PM > Subject: Re: [OS-webwork] Documentation > > >> I agree that the documentation should certainly be available out of the > box. >> >> My experience is that, however, one needs to make documentation as simple > as >> possible to write. >> >> Look at how much documentation and knowledge the Wiki has created compared >> to how much doco we had from people 'getting off their ass to write XML'. >> >> I would advise that we use the Wiki as much as possible. XML/XSLT is all >> magical, HTML is nice, but nothing beats speed. If we want people to write >> documentation, I suggest using the Wiki. >> >> Shipping this is another question though. I'd think (as the amount of >> documentation we have is relatively little!) we could pull it off the Wiki >> into another format at regular intervals, to make a PDF or HTML doc? >> >> (ie use the Wiki for editing, collating, moving, changing, writing - and >> then when we have something worth calling 'documentation' we put it into >> another format) >> >> From experience that will work best. >> >> My $0.02. >> >> Cheers, >> Mike >> >> PS That said, he who wants to write the documentation gets to choose how > it >> is done. >> >> On 11/12/02 3:39 AM, "Hani Suleiman" ([EMAIL PROTECTED]) penned the > words: >> >>> 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 >> >> >> >> ------------------------------------------------------- >> 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 >> > > > > ------------------------------------------------------- > 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 ------------------------------------------------------- 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
