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

Paul Everitt paul@digicool.com
Mon, 16 Jul 2001 06:52:59 -0400


On 7/16/01 5:48 AM, "seb bacon" <seb@jamkit.com> wrote:

>> Gitte (I think) wrote:
>> 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 also think this is a good idea.  In fact, I'd strengthen it and say,
instead of "like the Zope Book", just make the CMF a section of the Zope
Book.

The Zope Book (ZB) is meant to be a living creature that is updated before
every new Zope release goes out.  We at DC are committed to this.  The CMF
is likely on its track to the same kind of status.  This means that the work
done by us over here in the CMF can be "maintained" once written by a group
that includes the DC documentation team (Amos and Michel).

I've already talked with Amos about this.  He thinks it's a fine idea to
extend the two books (Zope Book and Zope Developers Guide) with sections of
chapters to cover the CMF for the two audiences.  We then won't have to
argue about machinery, etc.  Downside is that the ZB and ZDG don't use the
CMF or Zope for authoring, they use CVS.  But being pretty ruthless about
it, the point is writing docs not choosing tools.

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

The work on the ZB and ZDG tried to standardize audience jargon a bit, so
perhaps we could leverage that.  I'm in 100% agreement on the need.

> 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

I think there's an continuum of audiences (I might not have the jargon from
the Zope Book right):

  business decisionmaker -> content author -> site designer -> site
  developer -> component developer -> site administrator

> The presentation of the framework is currently very

Agreed.  I had some half-done material for a CMF Reviewer's Guide and some
other stuff.  Shoulda finished it. :^(

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

I agree that this is an important point and isn't emphasized enough.  Some
feel this point is one of the top 5 business things about the CMF -- instead
of being *your* CMS, it lets you quickly adapt or build your CMS.

Stated a different way...with Interwoven etc., you pay a bunch of money and
get their CMS.  If you spend a bunch of more money, you can turn it into
*your* CMS.  Ours is designed to quickly and cheaply build *your* CMS.

At least that's the theory. :^)

> 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

I agree that this isn't the greatest need.

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

Bingo, you're hitting the documentation nail on the head.  Which problems
does the CMF solve, and who does it solve them for?

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

I think there's a third piece, which is the 20,000ft (or 7km :^) view.  What
can this thing do?  I'm willing to start writing a series of Zope.org
spotlight articles on the kinds of problems CMF solves for content authors
and site developers.  Starting with: what is content management?

If we decided to do this a section of chapters for the Zope Book, then this
might be the first chapter.

> 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

Right, that's the problem domain of the survey chapter I was thinking about
starting.

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

Ohh, _installation_, now you wanna bring *that* up. :^)

--Paul