Hi, I've created a project in SVN labelled "zope3docs" and thought I'd let you know what I intend to start doing there. On the sprint last week we came to the conclusion that the current state how Zope 3 and its development process are documented is inadequate: documentation is scattered over many places, none of which can be referred to as "canonical" or "official" as they are (or at least seem) mostly outdated. I started to gather the existing material on how our development process works (including my memory) and try to combine it into a coherent whole without having the distractions of the cruft in the various old places. I also try hard to stay out of the tool business. ;) My short-term goal is to produce a document that I can pass to new developers with reasonable confidence that they know roughly how to move in our community. In the long term I'd also like to incorporate documentation about Zope 3 components themselve there. I'd be happy to get feedback on this and I'll probably come up with some questions if I can't find an answer in the existing documents. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 0 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Mon, Feb 2, 2009 at 11:49 AM, Christian Theune <ct@gocept.com> wrote:
I've created a project in SVN labelled "zope3docs" and thought I'd let you know what I intend to start doing there.
My short-term goal is to produce a document that I can pass to new developers with reasonable confidence that they know roughly how to move in our community.
A hearty +1 from me. I have very little time to spend, but I'm sure I'll at least read what you produce in hopes of helping how I can. -- Benji York Senior Software Engineer Zope Corporation
On Mon, Feb 2, 2009 at 8:49 AM, Christian Theune <ct@gocept.com> wrote:
My short-term goal is to produce a document that I can pass to new developers with reasonable confidence that they know roughly how to move in our community.
In the long term I'd also like to incorporate documentation about Zope 3 components themselve there.
Awesome!
I'd be happy to get feedback on this and I'll probably come up with some questions if I can't find an answer in the existing documents.
I'll ask the question of why not put this on the new.zope.org website? I think the obvious response is that it's easier to write docs in rst format and stick it in subversion than to write it out on the plone site where people don't get change notifications, etc. That said, it would be nice if these docs could somehow magically appear on the plone site (I'm told plone has some product for syncing content from subversion?). Alternatively, we could just generate the docs from the rst files but use the sphinx template I made in z3c.recipe.sphinxdoc that looks just like the plone site. Hopefully there is something I can contribute to these docs, but it looks like you've got a pretty good start on them. -- Paul Carduner http://www.carduner.net
On Mon, 2 Feb 2009 09:16:38 -0800 Paul Carduner <paulcarduner@gmail.com> wrote:
On Mon, Feb 2, 2009 at 8:49 AM, Christian Theune <ct@gocept.com> wrote:
My short-term goal is to produce a document that I can pass to new developers with reasonable confidence that they know roughly how to move in our community.
In the long term I'd also like to incorporate documentation about Zope 3 components themselve there.
Awesome!
I'd be happy to get feedback on this and I'll probably come up with some questions if I can't find an answer in the existing documents.
I'll ask the question of why not put this on the new.zope.org website?
.oO(Geez, we're bad at communicating internally ...) new.zope.org does not exist anymore. The project was cancelled a while ago. We can not use that layout. .oO(Hopefully the communication about this that ended up in my brain was correct) Nevertheless, you're right about the ease of writing ReST in my own editor. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 0 · fax +49 345 1229889 1 Zope and Plone consulting and development
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Feb 2, 2009, at 18:32 , Christian Theune wrote:
Nevertheless, you're right about the ease of writing ReST in my own editor.
What's even better: SVN-based documentation (or buildouts that create it) can be automated so that the site can be refreshed without human intervention. FYI: A while ago I created the http://docs.zope.org/ as a possible central address for collecting generated Zope documentation. jens -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.8 (Darwin) iEYEARECAAYFAkmHMvUACgkQRAx5nvEhZLIBsACePznehn/NTrIhuQb6lEd2c+my geoAnRr5Q5qhcJymcGippg5cYjJmtAXR =iT5g -----END PGP SIGNATURE-----
Christian Theune a écrit :
On Mon, 2 Feb 2009 09:16:38 -0800 Paul Carduner <paulcarduner@gmail.com> wrote:
On Mon, Feb 2, 2009 at 8:49 AM, Christian Theune <ct@gocept.com> wrote:
My short-term goal is to produce a document that I can pass to new developers with reasonable confidence that they know roughly how to move in our community.
In the long term I'd also like to incorporate documentation about Zope 3 components themselve there. Awesome!
I'd be happy to get feedback on this and I'll probably come up with some questions if I can't find an answer in the existing documents. I'll ask the question of why not put this on the new.zope.org website?
.oO(Geez, we're bad at communicating internally ...)
new.zope.org does not exist anymore. The project was cancelled a while ago. We can not use that layout.
there is not much design apart from the css, and a few illustrations. I've contributed some textual contents on this site, the folder arrangement, the get-started page, a few tutorials in the Example folder. You can retrieve everything and move it to the svn as rst files. I think we can keep the same kind of folder layout (Get Started, Projects with z2, z3 app, z3 library, zodb, etc.). Since the new site is not intended to be a collaborative space, we really don't need a Plone for that. A Sphinx is ideal. Christophe
.oO(Hopefully the communication about this that ended up in my brain was correct)
Nevertheless, you're right about the ease of writing ReST in my own editor.
Christian
On Mon, 02 Feb 2009 09:16:38 -0800, Paul Carduner wrote:
it would be nice if these docs could somehow magically appear on the plone site (I'm told plone has some product for syncing content from subversion?).
participants (6)
-
Benji York -
Christian Theune -
Christophe Combelles -
Jeff Kowalczyk -
Jens Vagelpohl -
Paul Carduner