Personally I find that I can write the fastest when I write in XML
because I do not have to think at all about the layout.
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)
+ Why webware
+ Webware vs JSP/PHP/...
Webware Core Concepts
+ Anatomy of a Webware transaction
+ Subclassing to a clean design
+ Start / Stop / NTService
+ 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
Advanced Form Handling
++ w/ Cheetah
++ w/ PSP
Setting Up a WorkSpace
+ Directory Layout
+ Code organization
+ Persentation layer vs Business Layer vs Data Layer
+ XML-RPC handler
++ Blog API
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.....)
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
> 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
> - Geoff
>>From: Ian Bicking [mailto:ianb@...]
>>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
>>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
>>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
>>wouldn't call directly.
>>And when you look at classes like HTTPServlet and Page, it
>>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.
>>This sf.net email is sponsored by: Influence the future
>>of Java(TM) technology. Join the Java Community
>>Process(SM) (JCP(SM)) program now.
> Webware-devel mailing list
> This sf.net email is sponsored by: Influence the future
> of Java(TM) technology. Join the Java Community
> Process(SM) (JCP(SM)) program now.
> Webware-discuss mailing list