[ZDP] Structure for ZDP site proposed

Craig Allen cba@mediaone.net
Wed, 12 May 1999 23:12:42 -0400

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

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
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,
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
	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

Would this work for folks?
- Craig
P.S. This is a great list!
Craig Allen  - Managing Partner - Mutual Alchemy
Information Architecture - http://alchemy.nu