[ZDP] Structure for ZDP site proposed

[Rik Hoekstra]

> Date:          Wed, 12 May 1999 23:12:42 -0400
> From:          Craig Allen <cba@mediaone.net>
> Organization:  Mutual Alchemy
> To:            "zdp@zope.org" <zdp@zope.org>
> Subject:       [ZDP] Structure for ZDP site proposed

> I spent a while reviewing the tables of contents to some of my computer books,
> to see how they structure the documentation.  As you can imagine, the range was
> wide.
> 
> At a high level, the structure that seems to make sense (to me) is:
>  - Introduction
>  - Tutorial
>  - Reference Guide
>  - How-To
> Like the spiral model of development, documentation doesn't have to provide the
> entire solution on the first pass.  And also like most software, most people
> don't use all the features.  As long as the material is covered in breadth and
> depth, and as long as I can find the piece I want - at the level I want - then
> I'm happy.
> 
> So enough with the worldview, on to specifics.   
> 
> I think what I'm trying to do is provide a mental map that would help me decide
> where to look (as a documentation consumer) or where to post (as a producer),
> and that includes both content area and level.  However, the outline below will
> not always answer those questions.
> 
> As far as format, there are lots of options.  A current and extensive CoolFAQ,
> with good search capabilties, a reasonable structure, and crosslinks(?) would be
> far preferable to any other structure that was unused.
> 
> Moving rapidly onto thinner ice, here's a proposal that could be implemented as
> a folder structure on zdp.zope.org. 
> 
> A.  Introducing Zope (shamelessly cribbed from "Java in a Nutshell")
> 	1. Geting started with Zope
> 		Why is Zope interesting?
> 		A simple example
> 	2. How Zope differs from [X, Y, Z]: [and?] an introduction to the Zen of Zope
> 	3. The building blocks of Zope
> 		Objects
> 		Methods
> 		Classes/Products
> 		etc.
> B.  Running Zope
> 	1. What you need before you start
> 	2. Installation and configuration (big topic on Zope mailing list)
> 	3. External interfaces (this may be premature here, I'm thinking of RDBMS,
> mail...)
> C.  Tutorial
> 	1. The user interface
> 	2. Starting to build (in Zope Managers Guide..) (do it in a Version!)
> 	3. Taking advantage of acquisition (O-O, more Zen...)
> 	4. Creating and building methods
> 	5. Making your site interactive (using forms and methods?)
> 	6. Controlling access
> 	7. Working with an external data source (Gadfly's available easily, porting to
> others...)
> 	8. Products and ZClasses
> 	9. External Methods
> 	10. The Zen of Zope revisited
> D.  Zope reference
> 	1. The components of Zope
> 		ZServer, ZPublisher, ZODB, etc.
> 	2. DTML tags
> 	3. Zope objects and their methods
> 	4. The source modules
> E.  How-To
> 	[I'm not sure how to structure this, but CoolFAQ would be a great presentation
> medium!]
>

Seems OK to me. Just a terrible lot of work. Would that mean all 
documentation is to be gathered on the ZDP site, or could there also 
be off site links?

Now, how to get this working:
I propose (as if I would have any authority) we officially adopt a 
scheme like this or something like it. Then, everyone who 
contributes any documentation indicates in what section or sections 
it belongs. Then the librarian or the document mapper or whoever 
else sees to it that it is incoroporated in a meaningful way. Does 
that make sense?

Rik