[ZDP] Documentation & Zbook

[Dody Gunawinata]

> > ZBook and that's it. When it runs well, we can talk again about other
> > initiative.
> >
> > First urgent task :
> >
> > - Table of contents for ZBook.
> 
> Ok, what about the tables of content as they were proposed in
> 
> http://www.zope.org/pipermail/zdp/1999-May/000262.html
>

> 
A bit of rant from me.

Zbook and beyond.

We don't have to explain everything up front. Tell the reader a bit
about what they are going to do, then do it (examples/tutorial), then in
the end of each chapters, we gives in
depth discussion or design tips for Zope based application.

So let's teach the 'reader' on HOW to do Zope first, not WHY..
Because if we started with the premise WHY, we are in the danger of
confusing new user.  We can always argue otherwise,
but the Why part has pretty much been documented by various documents
from DC/Community. (and if DC is currently working
on a new Developers guide, it presume would be in the 'why')

> http://www.zope.org/pipermail/zdp/1999-May/000184.html  : This table of contents show's the Why approach to the Zope
documents. 

However, let's developed ZBook in a framework, so that people can dive
straight in and write for ZBook at no time. In this way,
people can contribute a small amount of writing at a time and we can
reuse the current how-to's that is already available (and request
the orig. author to modify them for ZBook). 

How it should look like ?

First, let's have a set of people writing on a core content of each Zope
topics, with examples. 
Then have mini projects/Exercises/Special cases.

Exercises starts by challenging a reader to implement a special task
using the assumed knowledge that has
been acquired by reader. Some sort of homework to do (oh, remind me of
highschool :)

These exercises is an open ended short articles that is meant to be the
pluggable parts of Zbooks.
The amount of writing for this exercises should be minimal, so it should
encourage people to contribute this small snippets of code/writing.
The differences between this and a how-tos is that an exercise should be
complete. The exercise (the answer) should produce something
that is runnable, so the reader can see the result and learn from the
code provided.

Just to throw something in the discussion. (I'd like to see what Tom
has)

*ZBooks Frameworks* 


For dummies:
  A brief, just a brief brush on the topics of management console. 
  - Creating Folders.
  - Inserting Image, File, DTML methods, DTML Documents.
  

Essential parts:
- DTML 
  (for x in DTMLTags)
     What is X?
     How to use X?
     Any design tips for X?
     Examples:
     Exercise Projects (with answers)  

- External Methods
  - What is?
  - Creating External Methods
  - Using it
  - Discussions.
  - Exercise Projects (with answers)

- Storing data
  - ZODB3
  - SQL server

- Python (optional)
  - What is?
  - Where to learn it?
  - (for x in PythonStruc)
  
  - Exercise Projects (with answers)
  
- ZClasses
  - The concept
  - The way
  - How to do it
  - Files to watch

Products
  - How
  - Simple
  - Complex

Zen of Zope components
  - ZPublisher
  - ZWhatever.

Discussions of Zope
 - Why ?
 - How ?
 - Design consideration ?

Zope militancy  ;o)
 - CF bashing
 - Why Perl sucks
 - ASP is GOING DOWN
 - PHP ? Roxen ? Frontier ? Thumbs down

Extending Zope
 - Add a new DTML tags into Zope.
 - Changing object storage

Installation
 (Insert Kamon's TOC here)

Performance, tweak, advice.
 - Scalability tests
 - Benchmark configuration


etc..

So the framework would give the current how-tos writer a way to work
together and make their article has more impact to the community.
So we probably will have a "content topic" tree where writers can
"inherit and extends" :) I'll call it ZBook Content Library (ZCL)

So, any thoughts ?

Dody
> Rik
> 
> _______________________________________________
> ZDP maillist  -  ZDP@zope.org
> http://www.zope.org/mailman/listinfo/zdp