[Plone-docs] State of documentation area reorg and tasks ?

Post by Kamon Ayeva
Hi everybody,
I can invest some time this week-end and next week to help on ongoing
documentation tasks.
Since I've seen http://dev.plone.org/plone/ticket/9928, can someone
please give me a picture of the current state of the developers
manual, and how it affects tickets that I was assigned to
(Archetypes-related).
I can do my best to work on and close my old tickets.
Or suggest more priority tickets where help is needed ?

Since no one else seems to have replied I'll say what I know. Hope I'm
not stepping on anyones toes.

There's two potential developer manuals (or starts of the final manual)

http://plone.org/documentation/manual/developer-manual

and

http://plonemanual.twinapex.fi/ (which is sourced out of the
collective and generated by sphinx).

Obviously we need one manual that lives on plone.org but I don't think
it's clear yet which one this will be but if we have both being
published on plone.org then we can make that choice. The sooner we do
the sooner we know where to merge all the content into.

I said I'd write some scripts to transform the sphinx developer manual
into plone content and upload it into plone.org via xml-rpc.
Unfortunately I've discovered the xml-rpc interface to plone isn't
capable allowing creation of content.
I don't really know what software is able to be put onto plone.org but
these are things I can think of

a) Install wsapi4plone.core onto plone.org (and do periodic remote
uploads)
b) Install Reflecto (as limi suggested) or similar onto plone.org (and
pull manual via svn then transform)
c) something else?

Could someone contact me who has an overview on what the least pain
solution would be to getting outside content into plone.org and I'll
work on getting it done.

Also a comment that Martin made earlier on that the structure could be
similar to his mind map http://grab.by/iYS. It is for plone 5 but I
think it aims to present in a logical order and have everything in one
manual. I really like the current dexterity manual and how it gives a
complete five.grok tutorial inside it so it's a one stop shop. I'd
love to pull in zope, zcml and everything we need to work in one
place. For instance I only just discovered the invaluable ZCML
reference on http://apidoc.zope.org/++apidoc++/ the other day. I don't
see why we can't pull a Five version of that into a Plone manual.

Post by Kamon Ayeva
Cheers,
Kamon
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts
the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important
issues through
interactions with peers, luminaries and emerging and established
companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Raphael Ritz

2010-01-18 09:31:49 UTC

Dylan Jay wrote:
[..]

Post by Dylan Jay
I said I'd write some scripts to transform the sphinx developer manual
into plone content and upload it into plone.org via xml-rpc.
Unfortunately I've discovered the xml-rpc interface to plone isn't
capable allowing creation of content.
I don't really know what software is able to be put onto plone.org but
these are things I can think of

Are you sure?

While I've not tried that in years - and never on plone.org itself -
your remark triggered me re-releasing something I've written years
ago:

http://plone.org/products/scriptingcmf/

Maybe it can still help you to get started?

Raphael

Dylan Jay

2010-01-18 23:28:50 UTC

Post by Raphael Ritz
[..]

Are you sure?
While I've not tried that in years - and never on plone.org itself -
your remark triggered me re-releasing something I've written years
http://plone.org/products/scriptingcmf/

You are totally right. web scraping is a third option I forgot. I was
hoping to avoid it however but if all else fails it will work.

Dylan Jay

2010-01-23 18:17:21 UTC

Hi,

The manual is now uploaded to the knowledgebase area[1]. I'm assuming
that the redesign will get rid of the authors attributions as that no
longer makes sense right? If not I'll get Mikko to reupload it as it's
mainly his work.
All the code for uploading will be in the buildout in
collective.developermanual shortly. Next step will be to setup regular
reuploads every night. Of course if anyone wants to contribute to the
manual just read [2]

It's been transformed using transmogrifier blueprints from
pretaweb.funnelweb. There may be somethings not transformed right so
let me know and I'll fix them if I can. In particular PHC reference
manuals don't allow index pages so content from sphinx index pages is
currently missing. Also many of the styles aren't supported by this
plone theme so will need to be supported or transformed to something
that is.

[1] http://plone.org/documentation/kb/collective.developermanual
[2] http://plone.org/documentation/kb/collective.developermanual/introduction/updating-this-document.html

p.s. Thanks Raphael, the api snippets did help me and in the end most
of the calls were even xmlrpc.
Thanks Mikko for the awesome start to manual and the others that have
contributed.

Alexander Limi

2010-01-24 00:51:43 UTC

You don't have to re-upload, you can just change the owner in the metadata.

I believe the policy is:

- KB articles show author, since it's usually submitted by an individual,
and they should get the credit + people should know who to contact, etc.
- Manuals in the official manual section don't have individual credits on
the page, but are owned and maintained by the docs team collectively.

I do feel like this is more like a traditional manual that should be listed
front and center instead of in the KB area, especially since it's maintained
in SVN but it can definitely start out here for now. Just be careful,
since people might start editing it TTW.

It's been transformed using transmogrifier blueprints from

Post by Dylan Jay
pretaweb.funnelweb. There may be somethings not transformed right so
let me know and I'll fix them if I can.

Every title has the ugly ¶ character added. We are also adding native
automatic support for headline-means-anchor-link-too in Plone via JS, so I
would remove this if possible. :)

In particular PHC reference

Post by Dylan Jay
manuals don't allow index pages so content from sphinx index pages is
currently missing. Also many of the styles aren't supported by this
plone theme so will need to be supported or transformed to something
that is.

Cool, this is a great first step!

p.s. Thanks Raphael, the api snippets did help me and in the end most

Post by Dylan Jay
of the calls were even xmlrpc.
Thanks Mikko for the awesome start to manual and the others that have
contributed.

Yeah, I'm really excited about the content already!

--
Alexander Limi · http://limi.net

Mikko Ohtamaa

2010-01-24 15:06:44 UTC

Post by Alexander Limi
- KB articles show author, since it's usually submitted by an individual,
and they should get the credit + people should know who to contact, etc.
- Manuals in the official manual section don't have individual credits on
the page, but are owned and maintained by the docs team collectively.

Regarding collective.developermanual we could pull this information out from
SVN entries and have it is a separate page. Currently there is a separate
page, but it is maintained manually.

I think it would be proper to give credit if you contribute to the manual,
but individual pages are not "owned" so that anyone is encouraged to fill in
holes and fix the errors.

-Mikko

--
View this message in context: http://n2.nabble.com/State-of-documentation-area-reorg-and-tasks-tp4398400p4449352.html
Sent from the Documentation Team mailing list archive at Nabble.com.

Martin Aspeli

2010-01-24 02:33:52 UTC

Post by Dylan Jay
Hi,
The manual is now uploaded to the knowledgebase area[1]. I'm assuming
that the redesign will get rid of the authors attributions as that no
longer makes sense right? If not I'll get Mikko to reupload it as it's
mainly his work.
All the code for uploading will be in the buildout in
collective.developermanual shortly. Next step will be to setup regular
reuploads every night. Of course if anyone wants to contribute to the
manual just read [2]
It's been transformed using transmogrifier blueprints from
pretaweb.funnelweb. There may be somethings not transformed right so
let me know and I'll fix them if I can. In particular PHC reference
manuals don't allow index pages so content from sphinx index pages is
currently missing. Also many of the styles aren't supported by this
plone theme so will need to be supported or transformed to something
that is.
[1] http://plone.org/documentation/kb/collective.developermanual
[2] http://plone.org/documentation/kb/collective.developermanual/introduction/updating-this-document.html
p.s. Thanks Raphael, the api snippets did help me and in the end most
of the calls were even xmlrpc.
Thanks Mikko for the awesome start to manual and the others that have
contributed.

I think it's really great that this has made its way to plone.org where
it belongs! ;-)

I couple of suggestions:

- As Alex said, it's probably better as a manual than a kb article.
This really ought to be the basis for "the" manual for Plone development
in general.

- We shouldn't call it 'collective.developermanual'. That's the name
of a Python package where we put some reST source code. It has no
meaning to the intended audience and it's a terrible title. I'd just
call it the "Plone Python Development Manual" or some such.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

Dylan Jay

2010-01-24 14:28:56 UTC

I think it's really great that this has made its way to plone.org where
it belongs! ;-)

was always the plan :)

Post by Martin Aspeli
- As Alex said, it's probably better as a manual than a kb article.

happy to put in the manual section if I get access.

Post by Martin Aspeli
This really ought to be the basis for "the" manual for Plone
development
in general.
- We shouldn't call it 'collective.developermanual'. That's the name
of a Python package where we put some reST source code. It has no
meaning to the intended audience and it's a terrible title. I'd just
call it the "Plone Python Development Manual" or some such.

It was just a name to separate it from the other developer manual.
http://plone.org/documentation/manual/developer-manual/

Are we going to have two manuals in medium term till we workout which
is the right way to go or pick one now?

Israel Saeta Pérez

2010-01-25 16:55:19 UTC

Great work! Congrats! I thought I'd never see this done.

Post by Dylan Jay
All the code for uploading will be in the buildout in
collective.developermanual shortly. Next step will be to setup regular
reuploads every night. Of course if anyone wants to contribute to the
manual just read [2]

Is it possible to make the manual non-editable for non-privileged users
so nobody starts editing its contents TTW by mistake?

Post by Dylan Jay
[...]

- As Alex said, it's probably better as a manual than a kb article.
This really ought to be the basis for "the" manual for Plone development
in general.

The reason I suggested to leave this collective.developermanual in the
KB for is mainly the difference in contribution policies between the
manuals and the KB area. I know Mikko and many others want this manual
to be freely editable and without any QA review process, and that it
will potentially contain incomplete draft stuff, so either we:

a) Make an exception to the manuals area policies and allow this
collective.developermanual to live there. This would mean that we would
have a manual in the manuals area that wouldn't need any contributor
agreement to be edited, but only collective rights access, and so we
would have to be very careful about copyright confusions.

b) Leave it in the KB and don't break the main policies.

Please keep in mind that the KB, at least from my point of view, is
*not* designed to be a second-rank, low-quality documentation area. It's
just a solution to allow people who want to contribute free-form
documentation without having to fight with the manuals structure.

Post by Martin Aspeli
- We shouldn't call it 'collective.developermanual'. That's the name
of a Python package where we put some reST source code. It has no
meaning to the intended audience and it's a terrible title. I'd just
call it the "Plone Python Development Manual" or some such.

I agree. Should we call up a small poll on the title of this manual?

-- israel

Dylan Jay

2010-01-27 13:30:50 UTC

Hi,

The idea is to have one developer manual right? Otherwise it's going
to be confusing where to put what.

The way I see it we have two potential contenders of the "one" plone
development manual, the existing plone.org manual and the new
collective manual. Each has a different update process but both are
trying to be the same thing.

I'm not sure what the process is for making this decision. Are there
still documentation team meetings where stuff is decided. Is this open
for debate? Anyone know?

Hopefully I've answered Israel's questions about structure and quality
of the collective documentation further down. The options I can think
of are:

a) Let both manuals exist for a couple of months side by side in the
manuals area and then decide which to keep after that. Basically
experiment with the update process and see what produces better
content and which contributors and readers prefer.

b) Let both manuals exist for a couple of months, one in manuals
section, one in kb, and then decide which to keep after that

c) Decide on the collective manual and begin moving all content from
the current plone.org manual into it. If we change our minds later we
can always just keep the plone conversion and revert it to a normal
plone manual.

d) Decide the plone.org manual is the way forward and begin moving all
content from the collective manual into the plone.org manual. Let the
collective manual go somewhere else (probably just stay on Mikko's
site) or just give up on it.

e) Mix and match. In theory I can modify the upload script to follow
redirects (chances are it already does this). That means it's possible
move content out of the plone version of teh collective manual, put it
into the plone.org manual and yet still have it be regularly
overwritten by updates from the collective. Care would need to be
taken for editors to know which are "collective" pages of the manual
and which are plone editible pages, but I'm just noting this is
possible.

Great work! Congrats! I thought I'd never see this done.

Is it possible to make the manual non-editable for non-privileged users
so nobody starts editing its contents TTW by mistake?

I can't answer for sure but I'm guessing it just adds complexity to
have a special workflow for one item. Since the pool of manual editors
is smaller it might be easier to just educate them not the edit this
manual

I also remember hearing that the plan is to remove adding the
PHCManual type from the kb area so this is another reason why this
manual in the kb area might not make sense.

Post by Dylan Jay
[...]

- As Alex said, it's probably better as a manual than a kb article.
This really ought to be the basis for "the" manual for Plone
development
in general.

I think the main idea was to allow anyone with enough development mojo
to be able to contribute to the manual as naturally as possible (plus
also have the flexibility to pull in existing code documentation as
necessary). Separately from this Mikko and others argued for something
like the kb in addition so perhaps this is where the confusion came in?

There could be a QA review process for the collective manual.

In svn we have branches, so we could use a review process where
editors could review any new documentation before it's merged into the
plone3 branch or plone4 branch.

Alternatively we have the publishing step where it could be reviewed
before an uploading the content into plone.

Even if we use use neither of those processes above the mere fact that
someone has to be bothered to gain collective svn access and then edit
the reST which should filter out most "bad" contributions (touch wood).

Post by Israel Saeta PÃ©rez
a) Make an exception to the manuals area policies and allow this
collective.developermanual to live there. This would mean that we would
have a manual in the manuals area that wouldn't need any contributor
agreement to be edited, but only collective rights access, and so we
would have to be very careful about copyright confusions.

Copyright is a really good point. Again not 100% sure but I'd say that
the way the collective works is that by contributing to existing code
in there you are accepting that you are giving your rights up and
accepting whatever license and copyright is already attached to that
code. I can't see a license in collective.developermanual but I don't
see a problem with adding a creative commons one? Mikko?

Post by Israel Saeta PÃ©rez
b) Leave it in the KB and don't break the main policies.
Please keep in mind that the KB, at least from my point of view, is
*not* designed to be a second-rank, low-quality documentation area. It's
just a solution to allow people who want to contribute free-form
documentation without having to fight with the manuals structure.

collective.developermanual is a manual structure and is designed not
for people who want free-form documentation but rather who want to
fight the manuals structure.

I agree. Should we call up a small poll on the title of this manual?
-- israel
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts
the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important
issues through
interactions with peers, luminaries and emerging and established
companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez

2010-01-27 15:40:30 UTC

Hello,

Hi,
The idea is to have one developer manual right? Otherwise it's going to be
confusing where to put what.

Actually I'm not sure of this at all. Manuals and stuff in the KB can
coexist. Only the policies for the two areas are different, and we
explicitly agreed on the split specially because of the different policies
available for choice.

The way I see it we have two potential contenders of the "one" plone
development manual, the existing plone.org manual and the new collective
manual. Each has a different update process but both are trying to be the
same thing.
I'm not sure what the process is for making this decision. Are there still
documentation team meetings where stuff is decided. Is this open for debate?
Anyone know?

We still have an Editors Team which should ideally be responsible of making
the decisions, but in practice it has so few members that I think we will
have to apply a work-o-cracy: the people who works (or have worked) decide.
This includes, in my opinion, most of the editors and Veda, Steve, Anne
Botwell, Kamon, John Stahl, Alex, Mikko, Martin and you among others.

Hopefully I've answered Israel's questions about structure and quality of
a) Let both manuals exist for a couple of months side by side in the
manuals area and then decide which to keep after that. Basically experiment
with the update process and see what produces better content and which
contributors and readers prefer.
b) Let both manuals exist for a couple of months, one in manuals section,
one in kb, and then decide which to keep after that

Dylan Jay

2010-01-27 23:43:52 UTC

Post by Israel Saeta PÃ©rez
The manuals area is the manuals area because of its policies. As
I've already said in my previous email, the
collective.developermanual needs to live in the KB if we want to
respect these policies. So the only valid option above would be (b).

The collective developermanual is really a third policy that doesn't
fit into either camp.

Post by Israel Saeta PÃ©rez
The rest of options involve deciding now and I'd prefer to live with
both for some time, since I'm not sure at all of which one will work
best. IMO it's better and easier to try and see.

I was thinking the same however the downside in that approach is that
we might not give either a real "try". Since we'd have two competing
manuals we'd be splitting the contributors and the real problem all
these docs changes are trying to solve is to get more people
maintaining documentation.
If we pick c) and go out to the developer/integrator community with a
strong message saying "contribute here" we should get more uptake than
if we say "we haven't worked it out yet". People want to contribute to
something that will keep on living (plus lots of people do nothing
when confronted with a non obvious choice even if nothing is worse
than choosing). Of course this option is only going to work

The potential downside of c) is that after a few months we find the
manual isn't getting maintained by anyone new or the quality is crap
and so we pull the plug. Fortunately we'd have a fully plone editable
version of the collective manual due to the conversion process we use
so no downtime there. It would just be a matter of deleting the
collective manual and telling contributors they need to go plone.org
to edit the manual now.

We'd have to convert the current plone.org manual (and the tutorials
to be merged in) into reST. There exists python code to do that
conversion so I'll write transmogrify.html2rest and we'd have a
funnelweb commandline to pull down any plone content into local txt
files.

So I don't really see the downside in c).

Dylan Jay

2010-01-28 03:30:27 UTC

Forgot to say that whatever way we go it really needs to be a
consensus between those that currently write dev docs in addition to
considering how it could bring in new people. I havnt contributed to
either manual. I intend to however It takes me ages to write things
that are clear. My point is I don't recommend option c if a frequent
contributor such as Israel doesn't want to contribute any more.

Dylan Jay
Technical solution manager
PretaWeb 99552830

The collective developermanual is really a third policy that doesn't
fit into either camp.

Post by Israel Saeta PÃ©rez
The rest of options involve deciding now and I'd prefer to live
with both for some time, since I'm not sure at all of which one
will work best. IMO it's better and easier to try and see.

I was thinking the same however the downside in that approach is
that we might not give either a real "try". Since we'd have two
competing manuals we'd be splitting the contributors and the real
problem all these docs changes are trying to solve is to get more
people maintaining documentation.
If we pick c) and go out to the developer/integrator community with
a strong message saying "contribute here" we should get more uptake
than if we say "we haven't worked it out yet". People want to
contribute to something that will keep on living (plus lots of
people do nothing when confronted with a non obvious choice even if
nothing is worse than choosing). Of course this option is only going
to work
The potential downside of c) is that after a few months we find the
manual isn't getting maintained by anyone new or the quality is crap
and so we pull the plug. Fortunately we'd have a fully plone
editable version of the collective manual due to the conversion
process we use so no downtime there. It would just be a matter of
deleting the collective manual and telling contributors they need to
go plone.org to edit the manual now.
We'd have to convert the current plone.org manual (and the tutorials
to be merged in) into reST. There exists python code to do that
conversion so I'll write transmogrify.html2rest and we'd have a
funnelweb commandline to pull down any plone content into local txt
files.
So I don't really see the downside in c).

Israel Saeta Pérez

2010-02-03 00:15:32 UTC

I'm ok with either direction. I personally prefer the edit-TTW workflow
since I prefer to see my changes inmediately after web-edition instead
of having to fire an editor, compile some reST code (or worse, waiting
until the next compilation/publication takes place), etc.

My feel is that, except for extreme cases, what's important here to get
contributors is the editing/review workflow, and I think that we've
already come up with a good compromise solution with the manuals/kb
splitting.

-- israel

Post by Dylan Jay
Forgot to say that whatever way we go it really needs to be a
consensus between those that currently write dev docs in addition to
considering how it could bring in new people. I havnt contributed to
either manual. I intend to however It takes me ages to write things
that are clear. My point is I don't recommend option c if a frequent
contributor such as Israel doesn't want to contribute any more.
Dylan Jay
Technical solution manager
PretaWeb 99552830

The collective developermanual is really a third policy that doesn't
fit into either camp.

Post by Israel Saeta PÃ©rez
The rest of options involve deciding now and I'd prefer to live
with both for some time, since I'm not sure at all of which one
will work best. IMO it's better and easier to try and see.

I was thinking the same however the downside in that approach is
that we might not give either a real "try". Since we'd have two
competing manuals we'd be splitting the contributors and the real
problem all these docs changes are trying to solve is to get more
people maintaining documentation.
If we pick c) and go out to the developer/integrator community with
a strong message saying "contribute here" we should get more uptake
than if we say "we haven't worked it out yet". People want to
contribute to something that will keep on living (plus lots of
people do nothing when confronted with a non obvious choice even if
nothing is worse than choosing). Of course this option is only going
to work
The potential downside of c) is that after a few months we find the
manual isn't getting maintained by anyone new or the quality is crap
and so we pull the plug. Fortunately we'd have a fully plone
editable version of the collective manual due to the conversion
process we use so no downtime there. It would just be a matter of
deleting the collective manual and telling contributors they need to
go plone.org to edit the manual now.
We'd have to convert the current plone.org manual (and the tutorials
to be merged in) into reST. There exists python code to do that
conversion so I'll write transmogrify.html2rest and we'd have a
funnelweb commandline to pull down any plone content into local txt
files.
So I don't really see the downside in c).

Jan Ulrich Hasecke

2010-01-24 06:50:50 UTC

Post by Dylan Jay
[1] http://plone.org/documentation/kb/collective.developermanual
[2] http://plone.org/documentation/kb/collective.developermanual/introduction/updating-this-document.html

Insufficient Privileges

:-(
juh

Alexander Limi

2010-01-24 09:21:59 UTC

Try again. It's still in draft state, but I added you to the group that has
KB permissions.

On Sat, Jan 23, 2010 at 10:50 PM, Jan Ulrich Hasecke <

Post by Dylan Jay
[1] http://plone.org/documentation/kb/collective.developermanual
[2]

http://plone.org/documentation/kb/collective.developermanual/introduction/updating-this-document.html
Insufficient Privileges
:-(
juh
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important issues
through
interactions with peers, luminaries and emerging and established companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

--
Alexander Limi · http://limi.net

Mikko Ohtamaa

2010-01-24 15:01:39 UTC

Post by Dylan Jay
The manual is now uploaded to the knowledgebase area[1]. I'm assuming
that the redesign will get rid of the authors attributions as that no
longer makes sense right? If not I'll get Mikko to reupload it as it's
mainly his work.
All the code for uploading will be in the buildout in
collective.developermanual shortly. Next step will be to setup regular
reuploads every night. Of course if anyone wants to contribute to the
manual just read [2]

Greatness!

Can someone give me a sharing permission for the doc, so I can see what it
looks like :)

Great work there with upload, Dylan. I just eyed through the source code. Is
that true that you didn't have write a line of Python code to make this
happen? (or did you just update funnel itself...)

I can help to provide needed CSS to make the manual look proper. Also, I'll
edit the text so that it fits better to Plone-like folder / page structure
(Sphinx gives little more freedom regarding this and it has turned out that
freedom regarding index pages is not necessary a good thing).

-Mikko

--
View this message in context: http://n2.nabble.com/State-of-documentation-area-reorg-and-tasks-tp4398400p4449335.html
Sent from the Documentation Team mailing list archive at Nabble.com.

Dylan Jay

2010-01-24 15:59:24 UTC

Post by Mikko Ohtamaa

yes to both. Funnelweb got some bugs fixes/improvements, two new
transmogrifier blueprints for importing via xmlrpc and a commandline
interface. Nothing ended up being sphinx specific except the single
pipeline.cfg now included in collective.developermanual .
Transmogrifier is nice.

Post by Mikko Ohtamaa
I can help to provide needed CSS to make the manual look proper. Also, I'll
edit the text so that it fits better to Plone-like folder / page structure
(Sphinx gives little more freedom regarding this and it has turned out that
freedom regarding index pages is not necessary a good thing).

The first paragraph of the index pages is now used as the plone
description. Everything else is lost. The direct links to sub
headings on the sphinx heading pages is lost which is a shame.

e.g. compare
http://plone.org/documentation/kb/collective.developermanual/persistency
http://plonemanual.twinapex.fi/persistency/index.html

Maybe PHC could be updated to do the same?

Martin Aspeli

2010-01-24 16:10:33 UTC

Post by Dylan Jay
yes to both. Funnelweb got some bugs fixes/improvements, two new
transmogrifier blueprints for importing via xmlrpc and a commandline
interface. Nothing ended up being sphinx specific except the single
pipeline.cfg now included in collective.developermanual .
Transmogrifier is nice.

Yes, it is.

Are your blueprints available somewhere? I'd be interested to take a
look at how they use XML-RPC.

Also, someone needs to write a decent Transmogrifier manual. ;-)

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

Dylan Jay

2010-01-24 16:18:47 UTC

Yes, it is.
Are your blueprints available somewhere? I'd be interested to take a
look at how they use XML-RPC.

https://svn.plone.org/svn/collective/pretaweb.funnelweb/trunk/pretaweb/funnelweb/
remoteconstructor.py and remoteschemaupdater.py

Post by Martin Aspeli
Also, someone needs to write a decent Transmogrifier manual. ;-)
Martin
--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts
the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important
issues through
interactions with peers, luminaries and emerging and established
companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Martin Aspeli

2010-01-24 16:53:20 UTC

Post by Dylan Jay
https://svn.plone.org/svn/collective/pretaweb.funnelweb/trunk/pretaweb/funnelweb/
remoteconstructor.py and remoteschemaupdater.py

That looks really nice. How do you handle authentication? HTTP Basic?

Going off topic here, but:

I wish we could put each blueprint in a separate package, much like we
do with buildout recipes (which are analogous to blueprints in more than
one way). At least we should do this for re-usable ones. We already have
some precedent in transmogrify.sqlalcemy and transmogrify.filesystem.

Right now, people are experimenting with transmogrifier in more
integrated systems. It's good to have those, but the actual blueprints
should be in more granular, re-usable packages. I fear there's a lot of
overlap between something like pretaweb.funnelweb and
quintagroup.transmogrifier, for example. It can also be hard to re-use
these blueprints when they are not tested or designed to be used
independently. A small package with unit tests is much easier to
evaluate and integrate than a monolithic one.

I also worry about discoverability: I wouldn't have guessed that
pretaweb.funnelweb contained such useful recipes. ;)

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

Israel Saeta Pérez

2010-01-18 18:34:30 UTC

Just do anything Archetypes-related you need to do in
http://plone.org/documentation/manual/developer-manual/archetypes

Post by Kamon Ayeva
Or suggest more priority tickets where help is needed ?

Just look at https://dev.plone.org/plone/report/25 and choose what you
feel more comfortable with.

Plone 4 plips-related can be easy and quick to fix sometimes, and we
certainly need them to get done in a near future:
http://bit.ly/9304FG

Post by Dylan Jay
Since no one else seems to have replied I'll say what I know. Hope I'm
not stepping on anyones toes.
There's two potential developer manuals (or starts of the final manual)
http://plone.org/documentation/manual/developer-manual
and
http://plonemanual.twinapex.fi/ (which is sourced out of the
collective and generated by sphinx).
Obviously we need one manual that lives on plone.org but I don't think
it's clear yet which one this will be but if we have both being
published on plone.org then we can make that choice. The sooner we do
the sooner we know where to merge all the content into.

The approach I'm currently proposing is to leave both;
collective.developermanual as part of the KnowledgeBase, where
everywhere can contribute snippets of code freely, and the developer
manual in the manuals area of plone.org for more organized and
quality-controlled stuff. If we feel in the future that one of them is
not working, we can reconsider this.

-- israel

Kamon Ayeva

2010-01-18 19:10:02 UTC

Just do anything Archetypes-related you need to do in
http://plone.org/documentation/manual/developer-manual/archetypes

Ok.

Post by Kamon Ayeva
Or suggest more priority tickets where help is needed ?

Just look at https://dev.plone.org/plone/report/25 and choose what you
feel more comfortable with.

Sounds good to me.

Post by Israel Saeta PÃ©rez
Plone 4 plips-related can be easy and quick to fix sometimes, and we
http://bit.ly/9304FG

Ok, hopefully starting a personal Plone4-based project this week will
allow me to contribute there too.

Thanks for the pointers.

Regards,
Kamon

Dylan Jay

2010-01-18 23:24:32 UTC

The approach I'm currently proposing is to leave both;
collective.developermanual as part of the KnowledgeBase, where
everywhere can contribute snippets of code freely, and the developer

might be a bit confusing for contributors since kb will be widely
advertised as wiki style TTW editing but collective.developermanual
would be readonly in plone and edited via the collective. But I guess
we can try it that way if the permissions model allows it.

Post by Israel Saeta PÃ©rez
manual in the manuals area of plone.org for more organized and
quality-controlled stuff. If we feel in the future that one of them is
not working, we can reconsider this.

since we haven't really tried either approach (restricting to
collective access vs restricting to few doc team editors), I think
it's too early to say which method is going to result in the better
quality. I guess it makes sense to try both.

Post by Israel Saeta PÃ©rez
-- israel
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts
the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important
issues through
interactions with peers, luminaries and emerging and established
companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez

2010-01-19 00:08:34 UTC

Post by Israel Saeta PÃ©rez
The approach I'm currently proposing is to leave both;
collective.developermanual as part of the KnowledgeBase, where
everywhere can contribute snippets of code freely, and the developer

Right, but one of the reasons we're for using sphinx for some
documentation is that some contributors (mostly developers, I guess)
prefer editing restructured text with special advanced markup in ther
editors rather than using a web browser.

Anyway if we clearly indicate the different method to edit the kb
developermanual I don't think it will be a big problem.

-- israel

Alexander Limi

2010-01-19 06:19:01 UTC

Post by Israel Saeta PÃ©rez
Right, but one of the reasons we're for using sphinx for some
documentation is that some contributors (mostly developers, I guess)
prefer editing restructured text with special advanced markup in ther
editors rather than using a web browser.
Anyway if we clearly indicate the different method to edit the kb
developermanual I don't think it will be a big problem.

I think of the developer manual as analogous to the other manuals ie. has
a set number of people that can edit it (it just happens to be the core devs
instead).

It's not like a knowledge base article in terms of permissions. :)

--
Alexander Limi · http://limi.net

Veda Williams

2010-01-27 18:40:11 UTC

My 2 cents here is that I am not a developer, but it would be worth pulling
in the core developers to see what their feelings are about sphinx vs.
Plone. Whoever is most likely to contribute should have their vote weighed
more in this decision...

And I agree, work-o-cracy is probably the way to go here.

As a suggestion, I see no reason why the manuals page could not be updated
(perhaps by hand) to point to the KB manual. That way it¹s available in both
placed and editable by anyone.

Hi,
The idea is to have one developer manual right? Otherwise it's going to be
confusing where to put what.

Actually I'm not sure of this at all. Manuals and stuff in the KB can coexist.
Only the policies for the two areas are different, and we explicitly agreed on
the split specially because of the different policies available for choice.

The way I see it we have two potential contenders of the "one" plone
development manual, the existing plone.org <http://plone.org> manual and the
new collective manual. Each has a different update process but both are
trying to be the same thing.
I'm not sure what the process is for making this decision. Are there still
documentation team meetings where stuff is decided. Is this open for debate?
Anyone know?

We still have an Editors Team which should ideally be responsible of making
the decisions, but in practice it has so few members that I think we will have
to apply a work-o-cracy: the people who works (or have worked) decide. This
includes, in my opinion, most of the editors and Veda, Steve, Anne Botwell,
Kamon, John Stahl, Alex, Mikko, Martin and you among others.

Hopefully I've answered Israel's questions about structure and quality of the
a) Let both manuals exist for a couple of months side by side in the manuals
area and then decide which to keep after that. Basically experiment with the
update process and see what produces better content and which contributors
and readers prefer.
b) Let both manuals exist for a couple of months, one in manuals section, one
in kb, and then decide which to keep after that

The manuals area is the manuals area because of its policies. As I've already
said in my previous email, the collective.developermanual needs to live in the
KB if we want to respect these policies. So the only valid option above would
be (b).
The rest of options involve deciding now and I'd prefer to live with both for
some time, since I'm not sure at all of which one will work best. IMO it's
better and easier to try and see.
-- israel
------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

--
Veda Williams
Web Developer
Groundwire
206.286.1235x23
***@groundwire.org
http://groundwire.org

ONE/Northwest is now Groundwire!

Anne Bowtell

2010-01-27 20:43:25 UTC

+ 1

I vote for whatever will get the developer documentation written and
maintained most effectively.

Anne

Post by Veda Williams
My 2 cents here is that I am not a developer, but it would be worth
pulling in the core developers to see what their feelings are about
sphinx vs. Plone. Whoever is most likely to contribute should have
their vote weighed more in this decision...
And I agree, work-o-cracy is probably the way to go here.
As a suggestion, I see no reason why the manuals page could not be
updated (perhaps by hand) to point to the KB manual. That way its
available in both placed and editable by anyone.
------------------------------------------------------------------------
*Veda Williams*
Web Developer
Groundwire
206.286.1235x23
Groundwire
<http://groundwire.org?utm_source=Groundwire.org%2BEmail&utm_medium=Email&utm_campaign=Email%20%Signature;utm_content=Logo>
------------------------------------------------------------------------
ONE/Northwest is now Groundwire! Read all about our new name
<http://groundwire.org/about/our-new-name?utm_source=Groundwire.org%2BEmail&utm_medium=Email&utm_content=Read%2Ball%20about%20our%20new%20name&utm_campaign=Email%20%Signature>.
Hello,
Hi,
The idea is to have one developer manual right? Otherwise it's
going to be confusing where to put what.
Actually I'm not sure of this at all. Manuals and stuff in the KB
can coexist. Only the policies for the two areas are different,
and we explicitly agreed on the split specially because of the
different policies available for choice.
The way I see it we have two potential contenders of the "one"
plone development manual, the existing plone.org
<http://plone.org> manual and the new collective manual. Each
has a different update process but both are trying to be the
same thing.
I'm not sure what the process is for making this decision. Are
there still documentation team meetings where stuff is
decided. Is this open for debate? Anyone know?
We still have an Editors Team which should ideally be responsible
of making the decisions, but in practice it has so few members
that I think we will have to apply a work-o-cracy: the people who
works (or have worked) decide. This includes, in my opinion, most
of the editors and Veda, Steve, Anne Botwell, Kamon, John Stahl,
Alex, Mikko, Martin and you among others.
Hopefully I've answered Israel's questions about structure and
quality of the collective documentation further down. The
a) Let both manuals exist for a couple of months side by side
in the manuals area and then decide which to keep after that.
Basically experiment with the update process and see what
produces better content and which contributors and readers prefer.
b) Let both manuals exist for a couple of months, one in
manuals section, one in kb, and then decide which to keep
after that
The manuals area is the manuals area because of its policies. As
I've already said in my previous email, the
collective.developermanual needs to live in the KB if we want to
respect these policies. So the only valid option above would be (b).
The rest of options involve deciding now and I'd prefer to live
with both for some time, since I'm not sure at all of which one
will work best. IMO it's better and easier to try and see.
-- israel
------------------------------------------------------------------------
------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Alexander Limi

2010-01-27 22:03:00 UTC

Indeed. Ask on plone-dev what people would be most comfortable with. My
guess (hope? ;) is:

- Manual maintained in SVN, by Plone Committers (as it's easy to get
commit rights, I don't see this as being fundamentally different from
putting it in the Collective, and solves the ownership/licensing issue),
- Should be an official front-and-center manual in the docs area,
- Maintained as part of a Plone release (meaning, we can fork it for
Plone 4, etc when needed)

Post by Anne Bowtell
+ 1
I vote for whatever will get the developer documentation written and
maintained most effectively.
Anne
My 2 cents here is that I am not a developer, but it would be worth pulling
in the core developers to see what their feelings are about sphinx vs.
Plone. Whoever is most likely to contribute should have their vote weighed
more in this decision...
And I agree, work-o-cracy is probably the way to go here.
As a suggestion, I see no reason why the manuals page could not be updated
(perhaps by hand) to point to the KB manual. That way its available in both
placed and editable by anyone.
------------------------------
*Veda Williams* Web Developer Groundwire 206.286.1235x23
------------------------------
ONE/Northwest is now Groundwire! Read all about our new name<http://groundwire.org/about/our-new-name?utm_source=Groundwire.org%2BEmail&utm_medium=Email&utm_content=Read%2Ball%20about%20our%20new%20name&utm_campaign=Email%20%Signature>
.
Hello,
Hi,
The idea is to have one developer manual right? Otherwise it's going to be
confusing where to put what.
Actually I'm not sure of this at all. Manuals and stuff in the KB can
coexist. Only the policies for the two areas are different, and we
explicitly agreed on the split specially because of the different policies
available for choice.
The way I see it we have two potential contenders of the "one" plone
development manual, the existing plone.org <http://plone.org> manual and
the new collective manual. Each has a different update process but both are
trying to be the same thing.
I'm not sure what the process is for making this decision. Are there still
documentation team meetings where stuff is decided. Is this open for debate?
Anyone know?
We still have an Editors Team which should ideally be responsible of making
the decisions, but in practice it has so few members that I think we will
have to apply a work-o-cracy: the people who works (or have worked) decide.
This includes, in my opinion, most of the editors and Veda, Steve, Anne
Botwell, Kamon, John Stahl, Alex, Mikko, Martin and you among others.
Hopefully I've answered Israel's questions about structure and quality of
a) Let both manuals exist for a couple of months side by side in the
manuals area and then decide which to keep after that. Basically experiment
with the update process and see what produces better content and which
contributors and readers prefer.
b) Let both manuals exist for a couple of months, one in manuals section,
one in kb, and then decide which to keep after that
The manuals area is the manuals area because of its policies. As I've
already said in my previous email, the collective.developermanual needs to
live in the KB if we want to respect these policies. So the only valid
option above would be (b).
The rest of options involve deciding now and I'd prefer to live with both
for some time, since I'm not sure at all of which one will work best. IMO
it's better and easier to try and see.
-- israel
------------------------------
------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs
------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

--
Alexander Limi · http://limi.net

Dylan Jay

2010-01-28 03:40:32 UTC

Post by Alexander Limi
Indeed. Ask on plone-dev what people would be most comfortable with.
Manual maintained in SVN, by Plone Committers (as it's easy to get
commit rights, I don't see this as being fundamentally different
from putting it in the Collective, and solves the ownership/
licensing issue),
Should be an official front-and-center manual in the docs area,
Maintained as part of a Plone release (meaning, we can fork it for
Plone 4, etc when needed)

+1 esp. to branches on release.

/documentation/manual/developermanual/plone4/index

Are now maintainable with svn and the collective manual. (as much as i
wish it was just with plone too)

Post by Alexander Limi
+ 1
I vote for whatever will get the developer documentation written and
maintained most effectively.
Anne

Post by Veda Williams
My 2 cents here is that I am not a developer, but it would be worth
pulling in the core developers to see what their feelings are about
sphinx vs. Plone. Whoever is most likely to contribute should have
their vote weighed more in this decision...
And I agree, work-o-cracy is probably the way to go here.
As a suggestion, I see no reason why the manuals page could not be
updated (perhaps by hand) to point to the KB manual. That way itâs
available in both placed and editable by anyone.
Veda Williams
Web Developer
Groundwire
206.286.1235x23
ONE/Northwest is now Groundwire! Read all about our new name.
Hello,
Hi,
The idea is to have one developer manual right? Otherwise it's
going to be confusing where to put what.
Actually I'm not sure of this at all. Manuals and stuff in the KB
can coexist. Only the policies for the two areas are different, and
we explicitly agreed on the split specially because of the
different policies available for choice.
The way I see it we have two potential contenders of the "one"
plone development manual, the existing plone.org <http://
plone.org> manual and the new collective manual. Each has a
different update process but both are trying to be the same thing.
I'm not sure what the process is for making this decision. Are
there still documentation team meetings where stuff is decided. Is
this open for debate? Anyone know?
We still have an Editors Team which should ideally be responsible
of making the decisions, but in practice it has so few members that
I think we will have to apply a work-o-cracy: the people who works
(or have worked) decide. This includes, in my opinion, most of the
editors and Veda, Steve, Anne Botwell, Kamon, John Stahl, Alex,
Mikko, Martin and you among others.
Hopefully I've answered Israel's questions about structure and
quality of the collective documentation further down. The options I
a) Let both manuals exist for a couple of months side by side in
the manuals area and then decide which to keep after that.
Basically experiment with the update process and see what produces
better content and which contributors and readers prefer.
b) Let both manuals exist for a couple of months, one in manuals
section, one in kb, and then decide which to keep after that
The manuals area is the manuals area because of its policies. As
I've already said in my previous email, the
collective.developermanual needs to live in the KB if we want to
respect these policies. So the only valid option above would be (b).
The rest of options involve deciding now and I'd prefer to live
with both for some time, since I'm not sure at all of which one
will work best. IMO it's better and easier to try and see.
-- israel
---
---
---
---------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

---
---
---
---------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs
--
Alexander Limi Â· http://limi.net
---
---
---
---------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay

2010-01-31 23:57:33 UTC