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
