[ZWeb] Zope.Org Docs Page Draft

[Chris Withers]

Hi Mark,

Mark wrote:

> I have uploaded a pdf of how I would like to reorganize the Docs page ASAP.
> 
> Grab it here:
> 
> http://zope.org/Members/beehive/docspageV1.pdf/file_view

Well, the only significant change I can see here is a couple of high profile 
links to your paid-for publications ;-)

> Here are some specific things I would like to see changed:
> 
> Documentation Highlights
> 
> This section should be deleted. Because for one thing everything linked
> to is very, very, very old.

...and so are a lot of the other docs. This section needs *maintaining*, not 
deleting.

> Instead in the PDF you will find that Online Help has been moved to the 
> top.

Since both the hurt^whelp system and online tutorial are in pretty poor shape, 
is this really what we want to do?

> Note: After we have revised the Docs Section we might want to think 
> about how we can make Zope's help system a bit more useful -- including 
> a direct link to the Zope Docs section (which at least I couldn't find).

This needs to be done *carefully*. If you put links in a product, you restrict 
yourself from re-organising the site, and should really put permenant 
re-directing links if you *ever* move stuff. Again, not sure we want to commit 
to this right now...

> The Zope Documentation
> 
> section should either be called Zope.org Documentation 

Why?!

> or reflect the 
> name and link to external resources as well. 

Agreed.

> The PDF includes two sample 
> outside links one is to the SuperGuide for Newbies, 

I just had a scan through of this. It seems pretty thin on content useful to 
somone coming to zope :-( About the last three-sections-but-one actually seem to 
provide useful information to get started, and that's mainly in the form of a 
link to a VERY outdated how-to by Chris McDonough. (Zope 2.1.2? Hello?!) The 
Backup/Install section is probably the most accurate, but even that doesn't 
explain what <ZopeServer> is and does explain whether people should stop Zope 
before backing up, or whther it's safe to back it up while running. I also 
plants the common myth that "all objects are stored in one file, data.fs", which 
is a common reason for people to NOT choose Zope, despite it being a fallacy.

 > the other to the
> ZopeWiki.

Now here's a cool external resource I'd like to referred to more :-)

> In the PDF the link to the Zope Administrator's Guide Project. This 
> project has no active maintainer and when people go to read more about 
> it find out that the project
> is basically stalled We can link to it some other place.

A lot of the doc projects are stalled. I'm loath to just remove them, I'd like 
to see a note put on the stalled ones saying "help us maintain this!" instead.

> We need a well written overview of where and how people can contribute.
> (Contributing/Community Work). This should be *everyones* top priority 
> as it is in everybodies
> interest to find more volunteers to help with the tasks ahead.

Agree with this...

> Commercial Documentation
> 
> Recommend we remove the title (its kind of redundant)

Nope, it makes a clear distinction between "free" resources (in many different 
senses of the word) and non-free ones and as such is pretty imporant.

> and instead split 
> the current content into two parts.
> 
> - Articles
> - Books

...I totally agree with the other comments on this so far ;-)
This doesn't NEED two sections.

> Since Zope Corp already takes the time to provide a list of Zope books 
> we should just link to this page (saves a lot of screen real estate). 

Agreed.

> Lots of new Zope and Plone books coming so this is important to keep up 
> to date.

...but if it's on Zope.com, how do we do that? I'd suggest a Zope Books page on 
Zope.org and move that into the left-column-navigation.

>  From the current doc page there are two links to articles. One in the 
> left side navigation the other is part of the "Documentation Highlights" 
> called "Featured Articles". One is a dated list of articles that have 
> been published all over the web (a great idea) 

"Zope Articles", for anyone who spent 10 minutes trying to find this ;-)
(that left column nav also needs a good kicking...)
Yes it is a great idea, needs maintenence though. 1999 is hardly current...

> the other is a series of 
> articles written by employees of Zope Corp.

Really? I don't see a single ZC employee in that list.
Those articles are old, but still verymuch relevent.
They should probably drop in a more complete how-to's section...

> In the PDF you can see a link to ZopeMag 

Now there's a suprise ;-)

> and to a list of articles 
> published by companies world-wide (which should be actively maintained). 

By who? And for how long?

> I have the feeling that outside of ZopeMag less articles are being 
> published these days about Zope.

Well, I think you're slightly biased there ;-)

> I'd like to figure out a way to 
> introduce a featured article and help drive some traffic to publishers 
> who write about Zope.

Like ZopeMag? ;-)

> That's it for now. Awaiting your comments.

I'm kinda split on this. Not to waste words, it appears you're trying to do 
little more than drive traffic to ZopeMag. Doing that alone isn't exactly 
helpful, especially given the quality of the articles I've seen in ZopeMag so far...

However, provided you commit to maintaining the docs section in a fair and 
timely manner, I have no problem with you doing this. You do the work, you get 
the benefits.

What I'm worried about is you doing a quick dusting of the docs section which 
nets you some high profile links, after which the docs section see no more 
active maintenence from your good self ;-) There appears to be past precedent 
for this too...

Chris

-- 
Simplistix - Content Management, Zope & Python Consulting
            - http://www.simplistix.co.uk