But the fundamental problem is the content. I would not mind compiling a list somewhere of what docs we need. I would reccomend that we all work towards a single book. Collaborate on the table of contents and then individually write whatever section you can.
Something like (From Zope)
Introducing Webware
+ Why webware
+ Webware vs JSP/PHP/...
Webware Core Concepts
+ Anatomy of a Webware transaction
+ Subclassing to a clean design
Installing Webware
+ Dowload
+ CVS
+ Start / Stop / NTService
First Steps
+ Hello world
+ Hello world w/ sessions
+ Hello world w/ forms
+ Hello world w/ persisence
Database and Python
+ Installing MySQL / Postgres overview
+ Testing drivers
+ Seperating Data and Business layers
++ Creating object layer
+ Hello world w/ database
HTML generation
+PSP
+Cheetah
Advanced Form Handling
+Actions
+FunFormKit
++ w/ Cheetah
++ w/ PSP
Setting Up a WorkSpace
+ Directory Layout
+ Modules
+ Code organization
+ Persentation layer vs Business Layer vs Data Layer
XML
+ XML-RPC handler
++ Blog API
Appending
API ref
PSP ref
Cheeta ref
PSP ref
ETC......
I would stress how easily you can create clean maintainable code in this framework and the flexability of Python.
We already have much of the docs, If you all think this is a good path I'll do some cut 'n paste to get this started (although it took me 5 months to finish the last webware tutorial.....)
-Aaron
Geoffrey Talvola wrote:
I kinda like just using HTML with simple styles for documentation, as we are now. It works, it's easy to edit by hand, and it's just one less thing to learn.You're right, it's the content that's lacking, not the formatting. I don't really care one way or the other if we split it up or leave it in large pages. - Geoff-----Original Message-----.com/javavote
From: Ian Bicking [mailto:ianb@;colorstudy.com]
Sent: Thursday, October 24, 2002 3:42 AM
To: Webware devel
Cc: Webware discuss
Subject: [Webware-devel] Webware documentation
The Webware documentation isn't in very good shape, as it hasn't been
actively updated in a while.
Anyway, I've been writing lots of documentation lately, and I've been
using reStructuredText (http://docutils.sourceforge.net/rst.html). It's
worked pretty well for me -- the output looks decent, but more
importantly it's comfortable to write. Keeping the documentation
up-to-date is the most essential part.
In some way we should also split the documentation up for the different
parts -- Application, Adapters, Page, ... maybe all in the same file, or
a couple files... I'm not sure. Anyway, we could then really try to
keep it up to date with any changes to the code.
What do people think about reST? Docbook is spiffier, but I dread
actually writing it, and we're content-poor, not formating-poor.
Another option is utilizing doc strings for more. I'm not really sold
on it, but if someone feels more comfortable about generating real
documentation that way it might be a good idea. But generated
documentation like that just never looks quite right to me. It lacks
useful structure, it's bound to methods, and the documentation seems to
put trivial methods on par with important methods. But I'll look at
docutils more closely... though it's at an early stage. But I would be
open to tweaking docutils to make it work...
Actually, I guess my real issue is that inline documentation doesn't
distinguish between user interfaces and internal interfaces --
particularly when those internal interfaces are not entirely internal,
like methods that you may wish to override in a subclass, but which you
wouldn't call directly.
And when you look at classes like HTTPServlet and Page, it only confuses
people to present all that, when a document on servlets (in all forms)
would be much more helpful.
Anyway, those are some of my thoughts. I'd like to clean up a lot of
the documentation for 0.8.
Ian
-------------------------------------------------------
This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ad.doubleclick.net/clk;4729346;7592162;s?http://www.sun
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
-------------------------------------------------------
This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ad.doubleclick.net/clk;4729346;7592162;s?http://www.sun.com/javavote
_______________________________________________
Webware-discuss mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-discuss
-------------------------------------------------------
This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ad.doubleclick.net/clk;4729346;7592162;s?http://www.sun.com/javavote
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
