Could someone with adequate access please remove at least some of the garbage posts from the zope docs, the thousands of lines of spam/vandal nonsense make it really annoying to read. example: http://zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixD.stx -Mike Culbertson
On Mon, 24 Jan 2005 17:47:18 -0800, Mike Culbertson <mike@infoleak.com> wrote:
Could someone with adequate access please remove at least some of the garbage posts from the zope docs, the thousands of lines of spam/vandal nonsense make it really annoying to read.
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like). There's still a lot of cleaning up that's needed, but I don't have the time to do a lot of this myself. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> Zope Corporation
On Tue, Jan 25, 2005 at 12:23:16AM -0500, Fred Drake wrote:
... and I integrated a few comments into the text (mostly typo corrections and the like).
Great! ... only, I worry this will not make it into the 2.7 version of the book unless somebody takes care to merge your work? http://plope.com/Books/zb_signup The people working on appendices are listed there: 25 Appendix A: DTML Reference (David Siedband - in progress) 26 Appendix B: API Reference (Paul Winkler - in progress) 27 Appendix C: Zope Page Templates Reference (Thomas Reulbach - in progress) 28 Appendix D: Zope Resources (Jens Vagelpohl - finished) 29 Appendix E: DTML Name Lookup Rules (Jens Vagelpohl - finished) Which ones did you work on? -- Paul Winkler http://www.slinkp.com
On Tue, 25 Jan 2005 01:05:22 -0500, Paul Winkler <pw_lists@slinkp.com> wrote:
Great! ... only, I worry this will not make it into the 2.7 version of the book unless somebody takes care to merge your work?
Hmm. If the version on zope.org is not canonical, it shouldn't be editable (annotatable, yes, but not editable). I'd really like to see documentation maintained like other sources, using a revision control system (Subversion would be ideal, but CVS would be a step forward, IMO). Having yet another place to go doesn't help. Hopefully someone with the right access, Zen, and time will take a look at the changes and merge them into the source documents.
Which ones did you work on?
Appendices A-D. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> Zope Corporation
Hi Fred, Fred Drake wrote:
Hmm. If the version on zope.org is not canonical, it shouldn't be editable (annotatable, yes, but not editable).
Indeed. I don't think the BackTalk feature has really helped all that much, people just abuse it :-(
I'd really like to see documentation maintained like other sources, using a revision control system (Subversion would be ideal, but CVS would be a step forward, IMO). Having yet another place to go doesn't help.
There is a sourceforge project for this, how do we go about using it? cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Tue, Jan 25, 2005 at 08:49:41AM +0000, Chris Withers wrote:
Fred Drake wrote:
Hmm. If the version on zope.org is not canonical, it shouldn't be editable (annotatable, yes, but not editable).
Agreed. But I don't have access on zope.org to change the permissions on the book. I have no idea if the workflow even supports such a state.
Indeed. I don't think the BackTalk feature has really helped all that much, people just abuse it :-(
I disagree, having edited a chapter for the 2.6 edition and working on one for the 2.7 edition, many of the comments are invaluable.
I'd really like to see documentation maintained like other sources, using a revision control system (Subversion would be ideal, but CVS would be a step forward, IMO). Having yet another place to go doesn't help.
+1, a couple people volunteered to help me with appendix B and it's been a pain coordinating that "by hand". As always, lack of time is the big problem. -- Paul Winkler http://www.slinkp.com
Fred Drake wrote:
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like).
This could be a problem. The reason I've shyed away from doing anything is 'cos there seems to be confusion as to whether book development happens on Plope.com or Zope.org. Chris, can you comment? cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Tue, 2005-01-25 at 03:47, Chris Withers wrote:
Fred Drake wrote:
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like).
This could be a problem.
The reason I've shyed away from doing anything is 'cos there seems to be confusion as to whether book development happens on Plope.com or Zope.org.
Chris, can you comment?
It should likely happen according to http://www.plope.com/Books/zb_signup . - C
Chris Withers wrote:
Fred Drake wrote:
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like).
This could be a problem.
The reason I've shyed away from doing anything is 'cos there seems to be confusion as to whether book development happens on Plope.com or Zope.org.
Chris, can you comment?
cheers,
Chris
Why is development happening on Chris' site? I volunteer to work with him to make whatever he needs to happen on this end to get it back in one, logical place. A -- Zope Managed Hosting Systems Administrator/Software Engineer Zope Corporation (540) 361-1700
On Tue, 2005-01-25 at 09:47, Andrew Sawyers wrote:
Chris Withers wrote:
Fred Drake wrote:
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like).
This could be a problem.
The reason I've shyed away from doing anything is 'cos there seems to be confusion as to whether book development happens on Plope.com or Zope.org.
Chris, can you comment?
cheers,
Chris
Why is development happening on Chris' site? I volunteer to work with him to make whatever he needs to happen on this end to get it back in one, logical place. A
We moved the development to plope.com because zope.org is slower than molasses in winter (totally unacceptable response time for editing). I'm not sure what it will take to fix that or even if it can be fixed. I'd be happy to move development back to zope.org, but I admit if it's as slow as it has always been when we do, I won't have the patience to contribute very much. - C
Chris McDonough wrote:
On Tue, 2005-01-25 at 09:47, Andrew Sawyers wrote:
Chris Withers wrote:
Fred Drake wrote:
I've cleaned up some of the worst in the appendices, but there's a lot more to go through. I think I caught all the wiki spam in the appendices, and I integrated a few comments into the text (mostly typo corrections and the like).
This could be a problem.
The reason I've shyed away from doing anything is 'cos there seems to be confusion as to whether book development happens on Plope.com or Zope.org.
Chris, can you comment?
cheers,
Chris
Why is development happening on Chris' site? I volunteer to work with him to make whatever he needs to happen on this end to get it back in one, logical place. A
We moved the development to plope.com because zope.org is slower than molasses in winter (totally unacceptable response time for editing). I'm not sure what it will take to fix that or even if it can be fixed. I'd be happy to move development back to zope.org, but I admit if it's as slow as it has always been when we do, I won't have the patience to contribute very much.
- C "We" need a commitment to fix it; from the collective "us" and ZC. There are no other options IMNSHO. Driving you (anyone) away due to performance is unacceptable. Andrew
-- Zope Managed Hosting Systems Administrator/Software Engineer Zope Corporation (540) 361-1700
On Tue, 2005-01-25 at 09:58, Andrew Sawyers wrote:
"We" need a commitment to fix it; from the collective "us" and ZC. There are no other options IMNSHO. Driving you (anyone) away due to performance is unacceptable.
Well, the other option is to just continue using plope.com I suppose and only move them to zope.org when they are "done". Serving up the docs for reading and commenting from zope.org is fine performance-wise, but serving them up for editing them really isn't. Of course, getting "done" is a whole other story. ;-) I've been remiss in my duties here. - C
On Tue, Jan 25, 2005 at 10:07:11AM -0500, Chris McDonough wrote:
Well, the other option is to just continue using plope.com I suppose and only move them to zope.org when they are "done".
Or use the sourceforge book project CVS. I tend to agree w/ Fred and Chris W that this would be better and, in the long run, easier. -- Paul Winkler http://www.slinkp.com
On Tue, 2005-01-25 at 16:06, Paul Winkler wrote: Or use the sourceforge book project CVS.
I tend to agree w/ Fred and Chris W that this would be better and, in the long run, easier.
That'd be fine as well. The only real reason the dev versions are Backtalk now is in order to have them available for display to docs seekers. We could maybe just ditch Backtalk/STX altogether, but I'm not sure what the alternative is. I do think the commenting features are valuable, as much as they may be abused. I'll also note that the last change made to the development docs was many months ago, and I'm not sure that moving them into another system will improve that in any way. - C
On Tue, 25 Jan 2005 17:00:50 -0500, Chris McDonough <chrism@plope.com> wrote:
That'd be fine as well. The only real reason the dev versions are Backtalk now is in order to have them available for display to docs seekers. We could maybe just ditch Backtalk/STX altogether, but I'm not
There's no need to move away from STX, and doing so at this point would be a nuissance.
sure what the alternative is. I do think the commenting features are valuable, as much as they may be abused. I'll also note that the last change made to the development docs was many months ago, and I'm not sure that moving them into another system will improve that in any way.
I've no objection what-so-ever to making the documents annotatable, though it's not clear to me that BackTalk is the right way to do it. The problems I see are: 1. General editing in the non-canonical location is bad, and misleading for potential contributors. This is especially true for occaisional contributors like me. 2. Being able to incrementally update from the maintained version without losing annotations seems necessary, unless we require that all annotations be handled or integrated by the time the update is performed. Such a requirement is not acceptable. I don't know if BackTalk can be used that way, or can be easily modified to do so. Given the synchonization issue, I'd gladly give up the annotations if the documents became easier to update, and have the updates actually make it to the published version (regardless of where that is). -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> Zope Corporation
Fred Drake wrote:
I've no objection what-so-ever to making the documents annotatable, though it's not clear to me that BackTalk is the right way to do it. The problems I see are:
1. General editing in the non-canonical location is bad, and misleading for potential contributors. This is especially true for occaisional contributors like me.
Not being able to work in the "canonical" location at all kills the "ongoing contributor" pool, which is worse.
2. Being able to incrementally update from the maintained version without losing annotations seems necessary, unless we require that all annotations be handled or integrated by the time the update is performed. Such a requirement is not acceptable.
I don't know if BackTalk can be used that way, or can be easily modified to do so.
Given the synchonization issue, I'd gladly give up the annotations if the documents became easier to update, and have the updates actually make it to the published version (regardless of where that is).
The BackTalk version *is* the canonical version for Zope 2.7, so the synchronization issue doesn't exist. -1 to moving the project *anywhere* except to zope.org. -1 to moving it to zope.org until after its "author-hostile" problems get fixed. +1 to turning of annotations for the 2.6 version of the book on zope.org (any value there is long lost). Tres. -- =============================================================== Tres Seaver tseaver@zope.com Zope Corporation "Zope Dealers" http://www.zope.com
Tres Seaver wrote:
The BackTalk version *is* the canonical version for Zope 2.7, so the synchronization issue doesn't exist.
Which backtalk version though? The one on Plone.com or the one on Zope.org?
-1 to moving the project *anywhere* except to zope.org.
Agreed, after reading this thread. Sourceforge won't help here without more development work than is likely to happen.
-1 to moving it to zope.org until after its "author-hostile" problems get fixed.
Does this mean "officially" making Plope.com canonical until zope.org is ready?
+1 to turning of annotations for the 2.6 version of the book on zope.org (any value there is long lost).
If someone tells me how, I'll get on and do it... cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Tue, 2005-01-25 at 17:33, Fred Drake wrote:
1. General editing in the non-canonical location is bad, and misleading for potential contributors. This is especially true for occaisional contributors like me.
The canonical location is pretty broken ATM, however. At times, it can take several minutes to save a document. At least that was the case when we decided to move the development docs to plope.com.
2. Being able to incrementally update from the maintained version without losing annotations seems necessary, unless we require that all annotations be handled or integrated by the time the update is performed. Such a requirement is not acceptable.
AFAIK, there is no incremental update to be done from the maintained version. There is only one maintained version of the 2.7 book at the moment, and that's on plope.com. The 2.6 version is no longer maintained.
I don't know if BackTalk can be used that way, or can be easily modified to do so.
Given the synchonization issue, I'd gladly give up the annotations if the documents became easier to update, and have the updates actually make it to the published version (regardless of where that is).
I'm not sure there is a synchronization issue. There's definitely a locking issue... not allowing people to step on each others' changes. But this is currently handled manually (via the maintenance signup process) as well as via DAV locking. The 2.6 book commenting feature should be turned off now that the 2.7 book is in development. That it hasn't been is an oversight. When the 2.7 version is finished, it should accept comments (it currently doesnt). All that said, I'm happy to do whatever everybody else wants to do. I understand that not everyone is a fan of the commenting feature, although I do think it contributes immensely to the docs, especially during new version development. There is also a feature to turn *off* the comments on the viewed output but it appears that it's not "sticky" at the moment... it needs to be clicked for every page. Not sure why that is. That can be fixed, if it made any difference. - C
On Tue, Jan 25, 2005 at 05:00:50PM -0500, Chris McDonough wrote:
On Tue, 2005-01-25 at 16:06, Paul Winkler wrote:
Or use the sourceforge book project CVS.
I tend to agree w/ Fred and Chris W that this would be better and, in the long run, easier.
That'd be fine as well. The only real reason the dev versions are Backtalk now is in order to have them available for display to docs seekers. We could maybe just ditch Backtalk/STX altogether, but I'm not sure what the alternative is. I do think the commenting features are valuable, as much as they may be abused.
My thought was that the cvs project would just contain stx files that we can upload as Backtalk chapters. This would mean we should figure out a workflow for the ZODB data and a release process for the CVS data that allows us to merge in both directions (i.e. merge zope.org comments to CVS in preparation for editing a chapter, and lock the zope.org version for a short period of time to allow getting the cvs stuff ready to deploy; then upload to zope.org and unlock it.) This is basically what we're already doing on an informal basis. I've had to search through the zope.org version of Appendix B a couple times, looking for comments added since I started work. And I have to manually keep track of when I last did this.
I'll also note that the last change made to the development docs was many months ago, and I'm not sure that moving them into another system will improve that in any way.
You mean the dev guide? Yeah AFAIK nobody does much with it. -- Paul Winkler http://www.slinkp.com
Please god not another intermittently-available sourceforge CVS project.. we have a zope.org SVN repo, no ? I don't have a real answer to this problem, but I can tell you what the energetic ubuntu folks are doing just now. They started with a wiki (moin, then zwiki; imagine your-rapid-web-based-tool-of-choice here). The wiki was and is the primary place for making quick notes, gathering and organizing input from the wide user community with minimal hassle (after irc and the mail lists). Now they are working on some more formal docs in SVN using docbook, xml include features etc, which can generate multiple output formats. For these they harvest the wiki content (and eg 3rd party docs like ubuntuguide.org).
PS so, for anyone thinking about whether SVN/docbook might be the way to go, the ubuntu-doc archives are worth reading.
On Tue, 25 Jan 2005 16:13:34 -0800, Simon Michael <simon@joyful.com> wrote:
PS so, for anyone thinking about whether SVN/docbook might be the way to go, the ubuntu-doc archives are worth reading.
More specific pointers would be quite helpful. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> Zope Corporation
Fred Drake wrote:
More specific pointers would be quite helpful.
http://news.gmane.org/gmane.linux.ubuntu.doc I can't really point to specific messages, there's too much going on - but a good way to find things of interest might be to point thunderbird at nntp://news.gmane.org/gmane.linux.ubuntu.doc and filter on "ubuntu-doc report".
Chris McDonough wrote:
That'd be fine as well. The only real reason the dev versions are Backtalk now is in order to have them available for display to docs seekers. We could maybe just ditch Backtalk/STX altogether, but I'm not sure what the alternative is. I do think the commenting features are valuable, as much as they may be abused.
I agree, STX is fine, and comments are worthwhile provided there's a canonical place to update things crap comments can be weeded safely and good comments can be integrated back ASAP. The problem I see is that with a source repository, you'll forever be synching with the ZODB copy and worrying about comments. Years ago, I dreamed of something ViewCVS-ish that could render stuff instead of just checking it out, that way anyone could instantly view and comment on any branch and usual version control practices could be used to control what changes happen and where. Sadly, I don't think anyone has the time to develop such a beast ;-) So, I reckon we should stick with the current software, and do work in one canonical place. Although I do have some feature requests: - make that f'ing comments button stick, and be off by default ;-) - add a check box per chapter that lets an Editor lock a chapter for editing. This is a shroter term thn the chapter signup on Plope.org and just lets you lock the chapter so only you can edit, while you're editing. Anyone leaving a chapter in a locked state at any other time should be neutered...
I'll also note that the last change made to the development docs was many months ago, and I'm not sure that moving them into another system will improve that in any way.
Which development docs are you referring to? cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
participants (8)
-
Andrew Sawyers -
Chris McDonough -
Chris Withers -
Fred Drake -
Mike Culbertson -
Paul Winkler -
Simon Michael -
Tres Seaver