[ZWeb] Zope.Org Docs Page Draft

Mark mark at zopemag.com
Mon Jul 5 04:18:33 EDT 2004


Hello Chris,

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

I'm sorry I wasn't trying to make significant changes. This is V1. The  
goal was to reduce, simplify and
put something out there.

I added two links (one of which was to ZWiki) the other ZopeMag link is  
already on Zope.org
anyway and tried to move things around so that we get more space. The  
scope was limited --
but I took a first step. I'd like to encourage other people to come up  
with their own drafts or to give
some more suggestions / opinions about what else we should do or how to  
structure the information.

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

Agreed. But I think it is a really bad idea to link so prominently to a  
resource which hasn't
been updated since 2001 and the most recent comment being from 2002  
only to report
that it has officially stalled. I'm concerned about the first  
impressions here.

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

Well somebody thought it was important to point out before. I assume it  
is.

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

I certainly wouldn't want to change the URL for the docs page.

>> The Zope Documentation
>> section should either be called Zope.org Documentation
>
> Why?!
>
>> or reflect the name and link to external resources as well.
>
> Agreed.

I guess that answers your why?

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

Well thanks for that feedback. Part II is due next month and will of  
course continue with what we started.
Each part is about 15 to 20 pages. We will publish part III later this  
year. (these will all be free)


> > the other to the
>> ZopeWiki.
>
> Now here's a cool external resource I'd like to referred to more :-)

Sounds like we have an agreement :-)

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

On the Contributing/Community Work page -- absolutely!

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

Difference of opinion -- but I honestly don't care.

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

Totally disagree with the comments -- see the my answer to Jens.

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

Don't care where the page is located -- just that it exists and be kept  
up-to-date.

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

Obviously.

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

Well at the time of writing they were to my knowledge either employees  
or
independant contractors working for ZC -- but who cares? The idea was  
cool.


>> and to a list of articles published by companies world-wide (which  
>> should be actively maintained).
>
> By who? And for how long?

I'd love to help maintain this list because I want to know about and  
mention any articles for
example in our other "non for-pay" ZopeMag resource:

http://weekly.zopemag.com

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

My intention is certainly not to be biased -- I was sharing a  
perception.

Was actually hoping to see people post lots of links to this  
mailinglist of recent (less than 3 months) articles about Zope so that  
we can start updating the list.

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

Let me ask you a question: Do you know of any reason why articles that  
ZopeMag publishes for
free should not mentioned along with Zope articles in other  
publications?

I was actually thinking a lot about other publications -- who hopefully  
are writing lots of articles
about Zope. It would suck if ZopeMag was the only magazine writing  
about Zope.

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

I'm kind of confused about your statement. There already is a link to  
ZopeMag in the existing docs section of Zope.org -- if you think that  
my motivation for volunteering to coordinate the Docs section of  
Zope.org is to add a link to the SuperGuide your crazy.

As for the quality of ZopeMag articles I'm happy to report that I get a  
lot of email from subscribers saying
that they should have subscribed "a long time ago". And slowly but  
assuredly people are sharing their experiences with emails like this  
one to the mailinglists:

http://article.gmane.org/gmane.comp.web.zope.plone.user/19386/ 
match=zopemag

We are getting more articles submissions from our subscribers (Chris  
Curvey is one of them) who frequently are building on / referencing  
articles that other ZopeMag authors have written. Don't
think they would be / could be doing this if we didn't publish a few  
decent articles here and there?

But if you think that ZopeMag could use some improvement -- we are  
always looking for more writers
and would love to see you write for us sometime.

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

Thanks. Who can I negotiate with about the benefits? I'm not seeing  
many other than that i might have some fun and can contribute to a site  
that I really have an emotional attachment to. I can't stand seeing  
Zope.org in the current state that it is. See my previous emails to  
this mailinglist.

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

Don't really know what you are referring to -- but in my experience it  
is a common problem with OS
projects that people contribute something and then lose interest / have  
other obligations. I'm confident that I can make a contribution to the  
current effort because much of it relates to what I do in my regular  
day job.

Cheers,

Mark



More information about the Zope-web mailing list