Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Zope: Web

Zope.Org Docs Page Draft

 

 

Zope web RSS feed   Index | Next | Previous | View Threaded


mark at zopemag

Jul 4, 2004, 7:30 PM

Post #1 of 15 (1766 views)
Permalink
Zope.Org Docs Page Draft

Hi,

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

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.

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

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

The Zope Documentation

section should either be called Zope.org Documentation or reflect the
name and link to external resources as well. The PDF includes two
sample outside links one is to the SuperGuide for Newbies, the other to
the ZopeWiki.

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.

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.

Commercial Documentation

Recommend we remove the title (its kind of redundant) and instead split
the current content into two parts.

- Articles
- Books

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).
Lots of new Zope and Plone books coming so this is important to keep 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) the other is a
series of articles written by employees of Zope Corp.

In the PDF you can see a link to ZopeMag and to a list of articles
published by companies world-wide (which should be actively
maintained). I have the feeling that outside of ZopeMag less articles
are being published these days about Zope. I'd like to figure out a way
to introduce a featured article and help drive some traffic to
publishers who write about Zope. Ideally the traffic sent their way
will encourage them to publish even more articles about Zope in the
future.

That's it for now. Awaiting your comments.

Cheers,

Mark


jens at dataflake

Jul 4, 2004, 10:16 PM

Post #2 of 15 (1699 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

I don't see the need for that "Articles" section. I fully understand
that you would like more exposure for the ZopeMag, but I believe one
reference (like the one for that "SuperGuide for Newbies") is plenty.
That "Articles" section is nothing but free advertising for a for-pay
periodical.

jens

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


lists at andreas-jung

Jul 4, 2004, 10:26 PM

Post #3 of 15 (1695 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

--On Montag, 5. Juli 2004 1:16 Uhr -0400 Jens Vagelpohl
<jens [at] dataflake> wrote:

> I don't see the need for that "Articles" section. I fully understand that
> you would like more exposure for the ZopeMag, but I believe one reference
> (like the one for that "SuperGuide for Newbies") is plenty. That
> "Articles" section is nothing but free advertising for a for-pay
> periodical.
>

+1


_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


robert at redcor

Jul 4, 2004, 10:49 PM

Post #4 of 15 (1746 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

hoho
There are other articles that could be listed here. Arent there ?
It would be great to have such list some place, and an easy way to
contribute.

Robert

Jens Vagelpohl wrote:
> I don't see the need for that "Articles" section. I fully understand
> that you would like more exposure for the ZopeMag, but I believe one
> reference (like the one for that "SuperGuide for Newbies") is plenty.
> That "Articles" section is nothing but free advertising for a for-pay
> periodical.
>
> jens
>
> _______________________________________________
> Zope-web maillist - Zope-web [at] zope
> http://mail.zope.org/mailman/listinfo/zope-web
>
>
_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


mark at zopemag

Jul 5, 2004, 12:28 AM

Post #5 of 15 (1751 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Hello Jens,

I don't think you "get it". Yes it mentions ZopeMag (because it is the
*only*
Zope Magazine after all -- why shouldn't it be mentioned?). But the
"For a lists of
articles published by Magazines and website throughout the world click
here."
has not one iota to do with ZopeMag -- see:

http://www.zope.org/Resources/Articles/

for an example of what someone (don't know who) previously tried to
start for
Zope.org with links to lots of Zope articles in Magazines, websites
world-wide.

Articles by their very nature cover material that you will not find in
Books and are
a valuable resource.

On Jul 5, 2004, at 1:16 AM, Jens Vagelpohl wrote:

> I don't see the need for that "Articles" section. I fully understand
> that you would like more exposure for the ZopeMag, but I believe one
> reference (like the one for that "SuperGuide for Newbies") is plenty.
> That "Articles" section is nothing but free advertising for a for-pay
> periodical.

Even if I wasn't involved in a Magazine about Zope I would strongly
argue for a balance
of "contemporary" resources (articles) and reference (books).

I'd also like to point out that ZopeMag a "for-pay" Magazine publishes
much of its content for free.
For example this quarter 4 articles/product/reviews/guides will be
released for free. So consider
me biased but I would argue that we have a lot more articles/guides etc
that are worthwhile letting the community know about -- but the
SuperGuide for Newbies is the only one that makes sense to link to from
this page.

As for the SuperGuide for Newbies being all about exposure -- if their
was a single relatively
up-to-date Introduction for Zope Newbies that wasn't published by
ZopeMag I would want
it immediately added under the New Users heading feel free to point
more out to this list or take the time to write one. I'm still looking
for volunteers to help write the Overview for Contributing/Community
Work for example.

Cheers,

Mark

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


mark at zopemag

Jul 5, 2004, 12:33 AM

Post #6 of 15 (1730 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Hi,

On Jul 5, 2004, at 1:49 AM, robert rottermann wrote:

> hoho
> There are other articles that could be listed here. Arent there ?
> It would be great to have such list some place, and an easy way to
> contribute.

Exactly!

I can't stress how important it is to have an up-to-date list of
articles about Zope.
Some people will even see this as an indicator regarding adoption /
investing into
a techology. If nobody is writing about it -- is it relevant?

Cheers,

Mark

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


chris at simplistix

Jul 5, 2004, 12:40 AM

Post #7 of 15 (1759 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

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

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


mark at zopemag

Jul 5, 2004, 1:18 AM

Post #8 of 15 (1795 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

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

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


simon at joyful

Jul 5, 2004, 10:35 AM

Post #9 of 15 (1724 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

My two cents - the draft looks like a nice improvement. I would only
reword the Articles section. Mark your links to zopemag here and on
zopewiki come across with a marketing feel that is a bit of a turnoff -
zopemag is great and of course should be linked, but in a more neutral way.

The newbies superguide is in the right place. I'd be inclined to have
howtos, faqs, articles, books sections on an equal footing - why should
Articles & Books stand out more than the rest.

Thanks for tackling this thankless task, please don't stop. :)

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


mark at zopemag

Jul 5, 2004, 11:16 AM

Post #10 of 15 (1758 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Hello Simon,

On Jul 5, 2004, at 1:35 PM, Simon Michael wrote:

> My two cents - the draft looks like a nice improvement.

Thanks.

> I would only reword the Articles section. Mark your links to zopemag
> here and on zopewiki come across with a marketing feel that is a bit
> of a turnoff - zopemag is great and of course should be linked, but in
> a more neutral way.

Well then why don't you or someone else write a revised paragraph for
the Articles section?
That way it can't be biased towards ZopeMag.

> The newbies superguide is in the right place. I'd be inclined to have
> howtos, faqs, articles, books sections on an equal footing - why
> should Articles & Books stand out more than the rest.

I don't have a problem putting anything on equal footing -- its a
matter of space on the first page.
Take books for example by the end of the year I'm sure we will have
over 10 Books in print. A seperate page like the one on Zope.com makes
more sense.

As for How-to's, FAQs by all means we should add these. What would help
me is if some people could
write a paragraph and include a few links for each an I will add it to
the Graffle/PDF.

> Thanks for tackling this thankless task, please don't stop. :)

Appreciate the encouragement. Looking forward to working with you and
figuring out for example where linking to specific sections of the
ZWiki makes sense,

Cheers,

Mark

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


simon at joyful

Jul 5, 2004, 12:05 PM

Post #11 of 15 (1754 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

> figuring out for example where linking to specific sections of the ZWiki

The zopewiki, or just the wiki preferably. Wiki spelling and
nomenclature gets confusing. :)

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


simon at joyful

Jul 5, 2004, 12:11 PM

Post #12 of 15 (1698 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

> Well then why don't you or someone else write a revised paragraph for
> the Articles section?

I couldn't come up with something quickly. I would push it as-is, maybe
take out the first zopemag sentence, and keep refining it based on
suggestions here. Having it online adds motivation.

Later,
-Simon



_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


mark at zopemag

Jul 5, 2004, 12:30 PM

Post #13 of 15 (1699 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Hello again,

On Jul 5, 2004, at 3:11 PM, Simon Michael wrote:

>> Well then why don't you or someone else write a revised paragraph for
>> the Articles section?
>
> I couldn't come up with something quickly. I would push it as-is,
> maybe take out the first zopemag sentence, and keep refining it based
> on suggestions here. Having it online adds motivation.

That seems a bit too much like clear cutting to me. If there is a
dedicate magazine IMHO it should
be pointed out.

Here is a alternative shortened version of the Articles paragraph:

ZopeMag is a Magazine published quarterly about Zope. For a list of
articles published
by Magazines and websites throughout the world click click here.

Speaking of the articles. Can someone create a content type that allows
any user on Zope.org to submit these types of links?

Cheers,

Mark


chris at simplistix

Jul 12, 2004, 2:02 AM

Post #14 of 15 (1736 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Hi Mark,

Mark wrote:
> 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.

Who's "we" here? ;-)

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

I'm all for simplicity. That said, the much bigger problem is just keeping
whatever documentation is referred to from that page up-to-date...

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

Agreed. Bear in mind how true that is of a lot of documentation to do with Zope
though...

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

That was probably just after the help system was revised, sinc then it's fallen
in to disrepair due to lack of maintainence, which is a familar documentation
story...

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

Yes, but a single link to the docs page doesn't really add much...

>>> or reflect the name and link to external resources as well.
>>
>> Agreed.
>
> I guess that answers your why?

Well, I think Zope.org documentation implies documentation about the website
itself, which I think totally mis-labels this section...

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

That doesn't address the problems with Part I ;-)
I'd suggest totally rewriting Part I and bringing it up to date if you want to
use the term SuperGuide ;-)

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

And on the resource itself. People may be stirred into action if they go looking
for docs and find somewhere they can contribute, especially if they've just gone
through the pain and suffering of learning a new tools and found there were no
docs. You'll see PlacelessTranslationService grew a docs folder just recently ;-)

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

How's this coming?

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

Well, I can see your point, but for me "Documentation" implies the stuff in your
"Books" section. I'd break the Articles section off into a totally seperate and
longer page, updating as people add Articles to Zope an dpeople link to them on
Zope.org. I'd love to see an Article and Article Link content type on Zope.org
for this purpose...

We could vastly simplify the headings under the "Documentation" section in the
left nav. Afterall, how is anyone who doesn't know the answer to their problem
going to know to look in one of:
The Zope Book
Developer Guide
Administrator Guide
API Reference
(...etc...)

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

Okay, look forward to seeing it appear on Zope.org then :-)
Maybe someone from Zope.com could transplant the current page?

> 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 suggest posting again, with that as a subject on it's own. You may have more
joy asking for sucha response on the main Zope list, this this has a pretty
small readership...

> I'm kind of confused about your statement. There already is a link to
> ZopeMag in the existing docs section of Zope.org --

Yes, one small link at the same level as lots of other stuff ;-)

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

What're your rates?

Chris

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

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web


chris at simplistix

Jul 12, 2004, 2:07 AM

Post #15 of 15 (1742 views)
Permalink
Re: Zope.Org Docs Page Draft [In reply to]

Mark wrote:
> That seems a bit too much like clear cutting to me. If there is a
> dedicate magazine IMHO it should
> be pointed out.

That doesn't seem to be the opinion of others who've posted in this thread ;-)

> Here is a alternative shortened version of the Articles paragraph:
>
> ZopeMag is a Magazine published quarterly about Zope. For a list of
> articles published
> by Magazines and websites throughout the world click click here.

I'd prefer to see something like:

For a list of articles published by Magazines and websites throughout the world
click click <a href="article">here</a>.

And then in "articles":

The following publications are dedicated to Zope-related Subject:
<a href="">ZopeMag</a> - Qualterly publication, yada yada
<a href="">PloneMag</a> - Weekly publication, yada yada

The following articles have recently been published about Zope:
<a href="">Some article</a> - brief description, <date>.
<a href="">Some article</a> - brief description, <date>.
<a href="">Some article</a> - brief description, <date>.

And right now,as far as I know, ZopeMag would be the only entry in the top
section :-)

> Speaking of the articles. Can someone create a content type that allows
> any user on Zope.org to submit these types of links?

I believe you just volunteered ;-)

Seriously though, what's the process for adding new content types?

Chris

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

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web

Zope web RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.