From: Ian Bicking <ianb@co...> - 2002-10-31 03:08:30
Since several of you all are interested in docs, I thought I'd outline
what I was planning, for feedback or contributions.
I plan to make a new document, provisionally named "Getting Started"
(better names sought -- maybe just reuse the User Guide name) that will
outline everything a person needs to do to make their own application
using Webware. I'm not sure if I'll use an example app, or just talk in
the abstract. It will be fairly thorough, from configuration through
production (but won't include installation). I also want to include a
lot of notes about potential problems, good practice, and other advise
-- this should help people write *good* apps, not just working ones. I
think this fits in with what some people have talked about recently
regarding database pooling (BTW, databases should be a section if anyone
is interested in doing some writing).
I'll be copying some of the content from the User Guide, and when I'm
through I'm hoping it will be an alternative to the User Guide as a
While I'm hoping to make something thorough in breadth and opinion, I
*don't* want to include every detail -- only meaningful details. Things
like threading levels aren't going to be in there. To go along with
this guide I want to start working on a reference guide, which will
cover all details and interject little opinion or even guidance. The
reference can probably be organized by class and method, with special
sections for a few other concepts (like path decoding).
I'd really like to get both of these done before the 1.0 release, which
I think should be on our minds. (0.8 doesn't need complete docs -- I
think 1.0 should come after 0.8, though)
The last set of documentation I'd like to make is a developer guide for
understanding Webware itself and how to make contributions to it. It
would be meant to help someone get from developer-who-uses-Webware to
Webware Developer. Of course, reading code has a lot to do with this,
but other things (like Anatomy of a Webware Transaction) can help people
understand where to look, and how things fit together. Mostly I expect
it to give design maps and justifications. But it's kind of on the back
burner, and I don't think it needs to be finished for a 1.0 release.
I'm going to start plugging forward on GS/UG, concentrating more on
content than structure for now (cut and paste will give us structure