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

Reply via email to