[ZWeb] Documentation Page Changes

[ethan mindlace fremen]

Paul Everitt wrote:
> 
> Yeh, my ideas are a little bit more radical.  I was thinking in terms of
> adding value in different ways beyond organizing, by putting in some
> editorial.
> 
> Thus, instead of saying:
> 
> Zope Guides
> 
>   * Content Managers
> 
> ...I'd explain more about the Content Managers guide, and provide more
> directly addressable links.

It says "The Zope Content Manager's Guide introduces Zope and gives a gentle
introduction to creating and manipulating web objects." This explains the link
in my mind.  What do you mean by directly accessable links?

> Also, I was thinking about having the equivalent of "spotlight on" areas
> for documentation.  When something fun comes out, like Andrew Kuchling's
> article, or the intro to Zope on LinuxPlanet this week, or a great How
> To, find a way to bring it into view an onto people's radar.

I think this is a good idea: I'll implement it.

> I was also hoping to get a regular, weekly review of some artifact.
> Actually, I think this is better done on the home page:

Hm.  I think we need to be cautious about what we put on the home page. The 5
main topic items that are there already pretty much hit the limit of things that
people will look at, I think.  I'm certainly not against having a section in the
ZWN.

> """
> This weeks's hot picks:
> 
> Docs: Ever wonder how to use Apache's mod_proxy to interface with Zope?
> In the _Zope and mod_proxy How To_, Joe Sixpack goes into depth on this.
> Three stars out of four.
> 
> Products: .....
> 
> Site: .....
> 
> _More_...
> """
>
> And _More_ would lead to expanded reviews of each pick, plus links to
> old picks.

Expanded reviews of each pick?  So there would be an extended review ( 200 words
+ ) of a product, a doc, and some site feature every week? This is fairly labor
intensive.  If the community could submit reviews, that might work, but it
probably would lose a weekly flavor.
 
> Let's see, back to the docs page, I was thinking about reorganizing it.
> Instead of focusing on kinds of artifacts as the first level
> organization, instead focus on audiences.

Hm.  I personally dislike focus on audiences because I've traditionally been a
one-man band.  I think this is also a recipie for redundancy.  Almost everyone
needs the DTML reference, for example.

I'm trying to come up with other categories than content managers.  Unless we go
ahead and categorize the how- tos by audience, the pickings are going to be very
lean for Zope Administrators, for example.
 
> Content Managers
> 
>   Is your job creating and managing information stored in Zope, perhaps
> with a little scripting of that information?  Never expect to see a
> programming language?  The you're a content manager, and Zope is for you.
> 
>   Start with the _Content Managers Guide_ (_PDF_: 480Kb, _HTML_: 120 Kb)
> to quickly get an overview of working with Zope.  Next, ...
> 
>   Don't forget, Zope 2.2 now ships with an online help system, including
> an interactive tutorial!
> 
>   _More_
> 
> For each audience we can point them at the five most important things,
> then link them to a subpage that provides more complete intepretation.

I think that the Documentation page is too big.  I think the changes we're
looking at penalize people that know what document they want and want to use it
for reference (something I do all the time).

In a general sense, perhaps we should start to consider having a "newbie bit" or
somesuch so that experienced users can get to content quickly and newbies can be
hand-held.  Or Zope-web Geddon needs to focus on letting people customize their
experience with zope-web.

~ethan