[ZWeb] Oops, missed something

[Paul Everitt]

I think the first goal is to replace the current page at /Documentation
with something more meaningful.  There already is a lot of documentation
-- this page could do a better job organizing the docs and highlighting
the important stuff.

For instance, it's pretty hard to find the O'Reilly book material.  Last
week I added a link on the home Zope.org home page, but beyond that,
it's isn't prominently featured.

I think the documentation page should be organized into sections focused
on audiences.  The presentattion should follow follow the nascent style
guideline on the home page and other pages, having a section title, some
text, a few "quick links", and a link to "More...".  The link to more
would go to a page under documentation which exhaustively commented on
and summarized important documentation resources for that audience.

Both levels of pages should have "features" that highlight a
documentation resource or perhaps a person.

The proposed benefits are (a) better organization and (b) editorial
value (via summaries).

After that we can focus on prodding authors to get out-of-date stuff
rewritten.  I'll also note that we have a chunk of unreleased Zope
Developer Guide material.

So here's my proposal.

"""
Feature

  Ever want to get more performance out of your Zope site?  In his 
  _Zope and Squid_ How To, Itamar describes putting Squid, and http 
  accelerator and cache server, in front of Zope.  Itamar includes 
  specific details.  Three stars (out of four).

  Security Assertion Proposal | More...

Content Managers

  Zope provides a unique facility for turning control over to authors of 
  content.  These documentation resources describe Zope for content
managers.

  Zope Book | ZDP | More...

Developers

  Developing for Zope etc.

  DevShed Article | Product Tutorial | More...

Administrators


  Zope is installed and operated like other server applications, such 
  as Apache.  These documentation resources describe aspects of Zope 
  administration.

  ZAG | More...

Other Resources

  Zope has a growing amount of documentation, but this documentation 
  is spread across a number of sites.  The items listed here are good 
  places to look for more information on Zope.

  ZDP | Mailing Lists | More
"""

The lead item under "Feature" is a place to write reviews of
documentation resources and rate them.  The purpose here is two-fold:
help guide the readers to good documentation resources, but also to
encourage documenters to higher standards.  On the "More..." page would
be a longer review that revealed the pros and cons in the documentation
resource being reviewed.

Ethan previously posted my first cut at organizing some
developer-oriented documentation.

--Paul

Tom Deprez wrote:
> 
> >> Ok, can somebody give me a short explenation of what already is discussed
> >> concerning the documentation part of Zope.org?
> >
> >aside from my email about the technical issues, and paul's original email,
> there hasn't been much discussion.
> >
> 
> So, basically, what we've to do is, read all the documentation and put them
> together? Write documentation? Think on a new system for collecting and
> showing documentation?
> 
> Tom.
> 
> _______________________________________________
> Zope-web maillist  -  Zope-web@zope.org
> http://lists.zope.org/mailman/listinfo/zope-web