[Zope-CMF] Documentation / audiences (was Boring CMF Product)

seb bacon seb@jamkit.com
Mon, 16 Jul 2001 10:48:02 +0100


* Gitte Wange <gitte@mmmanager.org> [010716 08:25]:
> On Monday 16 July 2001 08:56, you wrote:
> > [Robert Rottermann]
> >
> > | I would sugest to split such a howto in chapters each one talking on
> > | on particular tool.
> >
> > Sounds like an idea.
> >
> > | This would mean to first scetch an "extensable" boring product.
> >
> > Yes.  I can have one up and running with in a day or three.
> >
> > | If you would detail me one of the parts, I would add one chapter.
> >
> > Once I've got the product up and running (bells and whistles turned
> > on) we can look at what needs to be done on the documentation part.
> >
> > Thanks! :)
> 
> I have been thinking of a CMF Book (something like the Zope Book).
> It shouldn't cover the same aspects as the Zope Book does, but perhaps tell 
> about all the things you need to be aware of when creating a "portal product".
> 
> Is this a good or a bad idea ?

I think this is an excellent idea.  I've been thinking a lot about
audiences lately, and feel that it's very important to identify and
prioritise the different possible targets for documentation, before
getting stuck into actually writing it.

It strikes me that there is a gaping hole in the CMF, between TTW site 
creation, and Product-based site creationl.  The distinction could be
phrased in a number of ways:

 technical focus - business focus
 python - dtml
 interfaces - implementation
 resources to develop custom system - no resources
 'zope zen' - beginner

The presentation of the framework is currently very
PythonProductDeveloper (PPD) oriented.  It comes down firmly in the
first column.  This is, overall, a good thing.  It's still a young
product and I'm happy that the focus is on interfaces rather than
implementation.  It gives me confidence that the CMF will be able to
grow into a complex system with the minimum of pain.

So, the CMF is driven by (excellent) technical design considerations,
and is at core a set of interfaces.  The CMFDefault is just one
implementation of these interfaces.  I think most newcomers to the CMF don't
understand this, and want to be able to build any site using the
CMFDefault, which is really not suited to the kind of template-driven
CMS which many people are apparently after.

So my point is, at whom should the documentation be addressed?  Those
with the greatest need are those in the right hand column, but I don't
feel documentation of a set of interfaces and an example
implementation is what they really need at the moment.  Rather, I
think the community should be building more CMF-based systems which
can be used to solve standard business problems out of the box - then
we should document them.  An example is Ausum's (and others') points
about refining the DefaultWorkflow.  His ideas are absolutely right,
but where do they belong?  The CMFDefault is designed to solve the
zope.org membership / content creation problem.  Should it be extended
with new ideas which might be aimed at solving other problems?  Which
problems are we trying to solve anyway?

With the CMF as it stands at the moment, the two possible focuses for
documentation are

  1) PPD documentation
  2) CMFDefault TTW documentation (a user's manual)

Apart from this, I'd like to see a push towards 

  1) defining the common business problems we think can be solved with
     the cmf
  2) implmenting solutions :-)

It would be great, for example, if there was a standard place for
finding new workflows, plus some instructions on how to install them.
Then we could move towards case studies showing how various CMF
components can be assembled to create the right solution.

I'd better stop before this email gets too long.  Does this strike a
chord with anyone else?

And just one other quick point: did anyone say what was wrong with
building on CMFCalendar as an example product?  That's what it was
made for originally.

cheers

seb