From: Ian B. <ia...@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 whole. 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 later). Ian |