Plone.org documentation: first do no harm

[Steve McMahon]

Sorry for weighing in on this so late.

Mikko, thanks for (re)starting this discussion, as well as for your
great contributions to the documentation. Your "Common Plone
programming recipes" may be our best document for helping new folks
learn how to manipulate content programatically.

I'd like to propose a little bit better-developed version of what I
pitched at the doc team panel in DC:

1) Contract the responsibility of the documentation team to a smaller
number of documents that are as authoritative and well-written as
possible. These would include end-user, integrator and developer
documentation, but not APIs. It would also aim at documenting one way
to do each thing -- not because there isn't more than one way to do
it, but because there's usually only one the community can really
support well. This should move towards being CC-licensed with an
agile-development methodology: anybody on the doc team that sees
something that needs fixing should fix it.

2) The documentation area's "developing for plone" manual would not do
APIs. It would be an orientation to each major topic. The "add-on
development for plone" manual or section, though, would cover things
like Archetypes (then dexterity) references.

3) The core development community would be encouraged in their efforts
to produced a more modular, packaged Plone with each package carrying
tests and documentation.

4) The doc team should let go of control of smaller, how-to and FAQ
type documents. Something like a wiki doesn't seem unreasonable to me,
though I'd argue that editing/contribution should require plone.org
membership. If a methodology or technique developed in the open area
becomes well accepted by the community, it should be added to the
doc-team-managed content and presented as authoritative. Maybe we
should even operate this under a different host name, (wiki.plone.org,
anyone?).


Steve

On Mon, Nov 10, 2008 at 4:23 PM, Mikko Ohtamaa
<[hidden email]> wrote:

>
> Hi everyone,
>
> I am not a very active follower of Plone documentation work. I am being more
> at the other end of the pipe, a casual document contributer.
> After being with Plone four years now, I'd like to bring in some of my
> thoughts, some partially related to the recent discussing
> ( http://n2.nabble.com/Community-practices-proposal-td1380405.html )
>
> I believe that the current Plone.org policy regarding documentation is too
> rigid - the barrier to contribute is too high, holding back
> the natural growth of what we could achieve. I try to grasp the concept of
> what I am thinking with an example.
>
> The problem with Plone documentation is not quality, it's quantity. We lack
> reference manual for TAL, Interfaces, GenericSetup XML,
> ZCML, you name it. I am honestly little skeptical whether Sphinx or whatever
> really cures the root cause of this - documentation
> team cannot simple fix the thing which is 300-500 pages of missing
> documentation out there which would make Plone a pleasant platform to work
> with.
> The most robust documentation and often still referred is Zope 2.7 book -
> nowadays sadly outdated.
>
> Because there is no documentation, making simple things become difficult. As
> a developer I often face a situation where I would need just two lines
> of code to make the thing happen. The answer is simple, but no one, except
> few core developers, know what those two lines might be.
> I have no clue of whatsoever to start investigating the issue, except the
> lenghty process to dig through the Plone codebase and try to figure
> out how the pieces of puzzles match together. But it is extremely
> cumbersome, since you don't know the picture what the puzzle should look
> like.
> If the core developers or anyone is not interested to help you, you are
> pretty much at the dead end.
>
> Here is one exampe to demostrate my point:
>
> http://plone.org/support/forums/general#nabble-td1213053
>
> I have discussed with fellow non-hardcore developers and they feel the same.
>
> Well, I still like Plone community and I try to get over with this and
> contribute my little findings back to the community, so that
> other poor bastards shouldn't face the same problems again, or at least
> they'd have a hint where to begun. After 8-12 hours of research
> to find out how to achieve my goal, I might blog about it or write a how to
> to plone.org. Of course, plone.org would be natural place,
> since then the poor bastard facing the same problem actually has a chance to
> find the solution by other means as punching random
> keywords in Google.
>
> (here is an example for punching keywords
> http://blog.redinnovation.com/2008/10/03/how-to-unit-test-security-declarations-in-plone-and-zope/
>  - but the answer is not correct and no one will ever probably fix it)
>
> The step to enter to the plone.org is high. First, you need an user account.
> Then you actually need to find a button "add how to".
> It's very well hidden and some people on #plone IRC channel didn't know such
> a button exist and they thought the submission was open
> for documentation team members only.
>
> On the rocky path these two obstacles can be easily overcome. But then the
> real problems begin. I have spent 12 hours to solve problem. I spent
> 2 hours to write the how to. I submit it. The usual canned response is "this
> is pretty good, but we need you to add this and this and this."
>
> I know it's not a personal insult against me, but it's really really
> frustrating. I feel like "guys, I spent 12 hours to solve this problem no
> one
> has ever published an answer. I spent two hours to write an answer for it,
> so that the next guy would need to spent only 6 hours on it.
> What do you expect me to do? I am not Hemmingway, I cannot sit all my work
> days polishing the How To to be just that perfect. Isn't my two hours
> enough, because the answer is there, mind the frames?"
>
> No, I am not going to post example code to collective. I am not going to
> extensively explain the backgrounds of my work. I just want to make
> the answer out there in a half decend attempt. It might not be a perfect
> answer, but it's still an answer and it would help dozens of people.
>
> ...where we arrive to the tipping point of my rant...
>
> plone.org documentation process is too rigid and currently needs heroic
> individuals to make anything show up there.
>
> If I wanted to make a TAL manual (
> http://n2.nabble.com/user/UserNodes.jtp?user=109797 ) I would have to write
> a perfect manual
> single handendly before the current process would actually publish it
> (well... I know this is not the case, but this is just a culmination).
> Say... three weeks of work before anyone can see the results and help me,
> unless I start recruiting people by running around.
>
> What I would like to see is a wiki. Plain simple wiki. I can throw in ideas,
> bits of code and *other people can pick where I drop the torch*.
> Currently Plone.org it does not give this opinion. The Archetypes recipe
> wiki as far back as 2004 has been the *best* documentation attempt for Plone
> in my opinion. It just got lost somewhere.
>
> With the current resources of the document team and hard-to-have
> contributions, it would take years to make that 500 page to have
> a decent Plone documentation - a key for pleasurable developing experience.
> Plone plays corporation game and sacrifies quantity for quality, but it
> really doesn't have the resources to drive in contributions, especially when
> the popularity of the project is steadily decreasing. Maybe the
> documentation team would have more fun when there would be some content to
> managent, instead of tossing those deprecated how tos written for Plone
> 2.0.x around?
>
> We all know this is the internets. Wikis have ~1000:1 (or something)
> contribution rate against closed gate systems
> (http://www.kuro5hin.org/story/2001/7/25/103136/121). No matter how many
> sprints or meetings the doc team has, no matter how many new processes it
> invents, it can't solve the problem of quantity.
>
> So, why are you holding back - just wikify the documentation?
>
> Just my two cents,
> Mikko
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> --
> View this message in context: http://n2.nabble.com/Plone.org-documentation-process-considered-harmful-tp1483044p1483044.html
> Sent from the Documentation Team mailing list archive at Nabble.com.
>
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
> Build the coolest Linux based applications with Moblin SDK & win great prizes
> Grand prize is a trip for two to an Open Source event anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>

--

Steve McMahon
Reid-McMahon, LLC
[hidden email]
[hidden email]

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Ricardo Newbery-2]

On Nov 12, 2008, at 9:01 AM, Steve McMahon wrote:

> Sorry for weighing in on this so late.
>
> Mikko, thanks for (re)starting this discussion, as well as for your
> great contributions to the documentation. Your "Common Plone
> programming recipes" may be our best document for helping new folks
> learn how to manipulate content programatically.
>
> I'd like to propose a little bit better-developed version of what I
> pitched at the doc team panel in DC:
>
> 1) Contract the responsibility of the documentation team to a smaller
> number of documents that are as authoritative and well-written as
> possible. These would include end-user, integrator and developer
> documentation, but not APIs. It would also aim at documenting one way
> to do each thing -- not because there isn't more than one way to do
> it, but because there's usually only one the community can really
> support well. This should move towards being CC-licensed with an
> agile-development methodology: anybody on the doc team that sees
> something that needs fixing should fix it.
>
> 2) The documentation area's "developing for plone" manual would not do
> APIs. It would be an orientation to each major topic. The "add-on
> development for plone" manual or section, though, would cover things
> like Archetypes (then dexterity) references.
>
> 3) The core development community would be encouraged in their efforts
> to produced a more modular, packaged Plone with each package carrying
> tests and documentation.

+1 on all of the above


> 4) The doc team should let go of control of smaller, how-to and FAQ
> type documents. Something like a wiki doesn't seem unreasonable to me,
> though I'd argue that editing/contribution should require plone.org
> membership. If a methodology or technique developed in the open area
> becomes well accepted by the community, it should be added to the
> doc-team-managed content and presented as authoritative. Maybe we
> should even operate this under a different host name, (wiki.plone.org,
> anyone?).


What is it about a wiki that appeals to you in this case?

The wiki-style editing window?  Which part?  The crippled structured-
text-like format?  The ability to add new pages by just adding a link  
to a current one?

Or is it the open editing environment with no editorial oversight?  Of  
course we wouldn't need a wiki for that.  We can do the same thing  
with regular page and folder types but with a simple publish workflow  
with very relaxed permissions.

In any case, I'm skeptical but as long as the entire "non-
authoritative" site clearly displays some sort of "reader beware"  
notice with a prominent link back to the authoritative collection, I  
guess it might be an improvement over the current state of affairs.

Instead of wiki.plone.org, how about non-authoritative.plone.org or  
unofficial.plone.org or anarchy.plone.org    ;-)

I still think it might be helpful to connect to the resources of the  
greater Plone community outside the plone.org domain via a targeted  
search engine or automated aggregator of some sort.  If we truly want  
to let go of control of the unofficial bits, let's go all the way and  
not host it but just provide a service to search or aggregate it.  
Perhaps even point potential contributors to third party hosts that we  
include in our search/aggregator.  Let a million flowers bloom.  ;-)

Ric




-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Jon Stahl]

> -----Original Message-----
> From: Ricardo Newbery [mailto:[hidden email]]
> > 4) The doc team should let go of control of smaller, how-to and FAQ
> > type documents. Something like a wiki doesn't seem unreasonable to
me,
> > though I'd argue that editing/contribution should require plone.org
> > membership. If a methodology or technique developed in the open area
> > becomes well accepted by the community, it should be added to the
> > doc-team-managed content and presented as authoritative. Maybe we
> > should even operate this under a different host name,
(wiki.plone.org,

> > anyone?).
>
>
> What is it about a wiki that appeals to you in this case?
>
> The wiki-style editing window?  Which part?  The crippled structured-
> text-like format?  The ability to add new pages by just adding a link
> to a current one?
>
> Or is it the open editing environment with no editorial oversight?  Of
> course we wouldn't need a wiki for that.  We can do the same thing
> with regular page and folder types but with a simple publish workflow
> with very relaxed permissions.
>
> In any case, I'm skeptical but as long as the entire "non-
> authoritative" site clearly displays some sort of "reader beware"
> notice with a prominent link back to the authoritative collection, I
> guess it might be an improvement over the current state of affairs.
>
> Instead of wiki.plone.org, how about non-authoritative.plone.org or
> unofficial.plone.org or anarchy.plone.org    ;-)
>
> I still think it might be helpful to connect to the resources of the
> greater Plone community outside the plone.org domain via a targeted
> search engine or automated aggregator of some sort.  If we truly want
> to let go of control of the unofficial bits, let's go all the way and
> not host it but just provide a service to search or aggregate it.
> Perhaps even point potential contributors to third party hosts that we
> include in our search/aggregator.  Let a million flowers bloom.  ;-)

Personally, I would be perfectly comfortable with their being a section
of plone.org/documentation that is the area for "community contributed,
unreviewed content" - use at your own risk, and please improve it!  I
dont' think there's much risk in keeping this stuff all in plone.org, as
long as it is clearly marked as such.

:jon

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Matthew Wilkes]

On 12 Nov 2008, at 20:31, Jon Stahl wrote:

> Personally, I would be perfectly comfortable with their being a  
> section
> of plone.org/documentation that is the area for "community  
> contributed,
> unreviewed content" - use at your own risk, and please improve it!  I
> dont' think there's much risk in keeping this stuff all in  
> plone.org, as
> long as it is clearly marked as such.

Would it be getting excessive to actually have a plone community  
website as well as a plone product and a plone providers website?

Something like plonecollective.org could have, for example:
1) Wild, wild west wiki style documentation, as above
2) Add-on products
3) Plone job board
4) User group listings

Just a left-field idea, but what do people think?

Matt

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[vedaw]

All rolled in with Plone.net (hosting providers)? Maybe also an inline view
of planet.plone, like we have with nabble? I'm not sure if that's really
possible, but it's a thought...

> Something like plonecollective.org could have, for example:
> 1) Wild, wild west wiki style documentation, as above
> 2) Add-on products
> 3) Plone job board
> 4) User group listings
>
> Just a left-field idea, but what do people think?
>
> Matt
>

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Jon Stahl]

> -----Original Message-----
> From: Matthew Wilkes [mailto:[hidden email]]
> Sent: Wednesday, November 12, 2008 12:50 PM
> To: Plone Docs List
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
>
> On 12 Nov 2008, at 20:31, Jon Stahl wrote:
>
> > Personally, I would be perfectly comfortable with their being a
> > section
> > of plone.org/documentation that is the area for "community
> > contributed,
> > unreviewed content" - use at your own risk, and please improve it!

I

> > dont' think there's much risk in keeping this stuff all in
> > plone.org, as
> > long as it is clearly marked as such.
>
> Would it be getting excessive to actually have a plone community
> website as well as a plone product and a plone providers website?
>
> Something like plonecollective.org could have, for example:
> 1) Wild, wild west wiki style documentation, as above
> 2) Add-on products
> 3) Plone job board
> 4) User group listings
>
> Just a left-field idea, but what do people think?

Love the functionalities, but I think we should avoid a profusion of
sites. I think our long term goal should be greater consolidation, not
more fragmentation.

:jon

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Matthew Wilkes]

On 12 Nov 2008, at 20:56, Jon Stahl wrote:

> Love the functionalities, but I think we should avoid a profusion of
> sites. I think our long term goal should be greater consolidation, not
> more fragmentation.

Yeah, but then you have to balance that with the implicit  
recommendation that's given when we host something on the official  
Plone website.  Bad documentation on Plone.org could easily get us  
into trouble, bad products less so.  I guess I'm just thinking that it  
would be good if we had something central for the community to own and  
Plone.org be very tightly controlled.

Currently we're making no visible distinction between the product and  
the community even though we have very good procedures in place to  
manage the product.  Again, I'm not sure if this is a good thing or  
not, but my instincts lean to not.

Matt

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Jon Stahl]

> -----Original Message-----
> From: Matthew Wilkes [mailto:[hidden email]]
> Sent: Wednesday, November 12, 2008 1:07 PM
> To: Jon Stahl
> Cc: Plone Docs List
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
>
> On 12 Nov 2008, at 20:56, Jon Stahl wrote:
>
> > Love the functionalities, but I think we should avoid a profusion of
> > sites. I think our long term goal should be greater consolidation,

not

> > more fragmentation.
>
> Yeah, but then you have to balance that with the implicit
> recommendation that's given when we host something on the official
> Plone website.  Bad documentation on Plone.org could easily get us
> into trouble, bad products less so.  I guess I'm just thinking that it
> would be good if we had something central for the community to own and
> Plone.org be very tightly controlled.
>
> Currently we're making no visible distinction between the product and
> the community even though we have very good procedures in place to
> manage the product.  Again, I'm not sure if this is a good thing or
> not, but my instincts lean to not.

Yeah, there's a definite tradeoff here, and I share the concern. I think
we can manage that with appropriate sections, permissions and
disclaimers, rather than really strongly separated sites.  

:jon

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

> -----Original Message-----
> From: Steve McMahon [mailto:[hidden email]]
> Sent: Thursday, 13 November 2008 4:01 AM
> To: [hidden email]
> Subject: [Plone-docs] Plone.org documentation: first do no harm
>
> Sorry for weighing in on this so late.
>
> Mikko, thanks for (re)starting this discussion, as well as for your
> great contributions to the documentation. Your "Common Plone
> programming recipes" may be our best document for helping new folks
> learn how to manipulate content programatically.
>
> I'd like to propose a little bit better-developed version of what I
> pitched at the doc team panel in DC:
>
> 1) Contract the responsibility of the documentation team to a smaller
> number of documents that are as authoritative and well-written as
> possible. These would include end-user, integrator and developer
> documentation, but not APIs. It would also aim at documenting one way
> to do each thing -- not because there isn't more than one way to do
> it, but because there's usually only one the community can really
> support well. This should move towards being CC-licensed with an
> agile-development methodology: anybody on the doc team that sees
> something that needs fixing should fix it.
>
> 2) The documentation area's "developing for plone" manual would not do
> APIs. It would be an orientation to each major topic. The "add-on
> development for plone" manual or section, though, would cover things
> like Archetypes (then dexterity) references.

+1 to all the above except that I think "developing with Plone" could be
done in svn and sphinx and then republished back into the
Plone.org/documentation space.
I think its much more helpful to developers to have api and core references
as close together as possible.
Such core documentation should be versioned and kept up to date with each
Plone release, ensuring we always have documentation for the next release
and its easy to find what the "core manual" looked like for a previous
release.
Also it would be a lot less coding move those docs into sphinx than it would
be create a book structure from the existing PHC content types I would
guess.
 
> 3) The core development community would be encouraged in their efforts
> to produced a more modular, packaged Plone with each package carrying
> tests and documentation.

+1
But I think that if the apis were together with reference docs the
"developing with Plone" would be highlighted and used much more which would
in turn "expose" the bad module documentation more. No one wants to write
documentation no one sees and seeing that people will see and in a useful
form, it might make people write docs more.
The readmes on pypi are a good example of that. I'd say people write them
much more now if they publish to pypi.

> 4) The doc team should let go of control of smaller, how-to and FAQ
> type documents. Something like a wiki doesn't seem unreasonable to me,
> though I'd argue that editing/contribution should require plone.org
> membership. If a methodology or technique developed in the open area
> becomes well accepted by the community, it should be added to the
> doc-team-managed content and presented as authoritative. Maybe we
> should even operate this under a different host name, (wiki.plone.org,
> anyone?).

Like others I think new domains aren't helpful.

I'd see something more like this

Plone.org/docs/user -> doc team stuff
Plone.org/docs/dev/manual -> sphnix
Plone.org/docs/dev/faq -> open editing with email notifications
Plone.org/products -> PSC which would have its own docs per product

I'm not sure where or how integrator documentation differs from developer
documentation since its all about working with the core code. Perhaps there
is scope to separate theming out from developer docs??

>
> Steve
>
> On Mon, Nov 10, 2008 at 4:23 PM, Mikko Ohtamaa
> <[hidden email]> wrote:
> >
> > Hi everyone,
> >
> > I am not a very active follower of Plone documentation work. I am being
> more
> > at the other end of the pipe, a casual document contributer.
> > After being with Plone four years now, I'd like to bring in some of my
> > thoughts, some partially related to the recent discussing
> > ( http://n2.nabble.com/Community-practices-proposal-td1380405.html )
> >
> > I believe that the current Plone.org policy regarding documentation is
> too
> > rigid - the barrier to contribute is too high, holding back
> > the natural growth of what we could achieve. I try to grasp the concept
> of
> > what I am thinking with an example.
> >
> > The problem with Plone documentation is not quality, it's quantity. We
> lack
> > reference manual for TAL, Interfaces, GenericSetup XML,
> > ZCML, you name it. I am honestly little skeptical whether Sphinx or
> whatever
> > really cures the root cause of this - documentation
> > team cannot simple fix the thing which is 300-500 pages of missing
> > documentation out there which would make Plone a pleasant platform to
> work
> > with.
> > The most robust documentation and often still referred is Zope 2.7 book
> -
> > nowadays sadly outdated.
> >
> > Because there is no documentation, making simple things become
> difficult. As
> > a developer I often face a situation where I would need just two lines
> > of code to make the thing happen. The answer is simple, but no one,
> except
> > few core developers, know what those two lines might be.
> > I have no clue of whatsoever to start investigating the issue, except
> the
> > lenghty process to dig through the Plone codebase and try to figure
> > out how the pieces of puzzles match together. But it is extremely
> > cumbersome, since you don't know the picture what the puzzle should look
> > like.
> > If the core developers or anyone is not interested to help you, you are
> > pretty much at the dead end.
> >
> > Here is one exampe to demostrate my point:
> >
> > http://plone.org/support/forums/general#nabble-td1213053
> >
> > I have discussed with fellow non-hardcore developers and they feel the
> same.
> >
> > Well, I still like Plone community and I try to get over with this and
> > contribute my little findings back to the community, so that
> > other poor bastards shouldn't face the same problems again, or at least
> > they'd have a hint where to begun. After 8-12 hours of research
> > to find out how to achieve my goal, I might blog about it or write a how
> to
> > to plone.org. Of course, plone.org would be natural place,
> > since then the poor bastard facing the same problem actually has a
> chance to
> > find the solution by other means as punching random
> > keywords in Google.
> >
> > (here is an example for punching keywords
> > http://blog.redinnovation.com/2008/10/03/how-to-unit-test-security-
> declarations-in-plone-and-zope/
> >  - but the answer is not correct and no one will ever probably fix it)
> >
> > The step to enter to the plone.org is high. First, you need an user
> account.
> > Then you actually need to find a button "add how to".
> > It's very well hidden and some people on #plone IRC channel didn't know
> such
> > a button exist and they thought the submission was open
> > for documentation team members only.
> >
> > On the rocky path these two obstacles can be easily overcome. But then
> the
> > real problems begin. I have spent 12 hours to solve problem. I spent
> > 2 hours to write the how to. I submit it. The usual canned response is
> "this
> > is pretty good, but we need you to add this and this and this."
> >
> > I know it's not a personal insult against me, but it's really really
> > frustrating. I feel like "guys, I spent 12 hours to solve this problem
> no
> > one
> > has ever published an answer. I spent two hours to write an answer for
> it,
> > so that the next guy would need to spent only 6 hours on it.
> > What do you expect me to do? I am not Hemmingway, I cannot sit all my
> work
> > days polishing the How To to be just that perfect. Isn't my two hours
> > enough, because the answer is there, mind the frames?"
> >
> > No, I am not going to post example code to collective. I am not going to
> > extensively explain the backgrounds of my work. I just want to make
> > the answer out there in a half decend attempt. It might not be a perfect
> > answer, but it's still an answer and it would help dozens of people.
> >
> > ...where we arrive to the tipping point of my rant...
> >
> > plone.org documentation process is too rigid and currently needs heroic
> > individuals to make anything show up there.
> >
> > If I wanted to make a TAL manual (
> > http://n2.nabble.com/user/UserNodes.jtp?user=109797 ) I would have to
> write
> > a perfect manual
> > single handendly before the current process would actually publish it
> > (well... I know this is not the case, but this is just a culmination).
> > Say... three weeks of work before anyone can see the results and help
> me,
> > unless I start recruiting people by running around.
> >
> > What I would like to see is a wiki. Plain simple wiki. I can throw in
> ideas,
> > bits of code and *other people can pick where I drop the torch*.
> > Currently Plone.org it does not give this opinion. The Archetypes recipe
> > wiki as far back as 2004 has been the *best* documentation attempt for
> Plone
> > in my opinion. It just got lost somewhere.
> >
> > With the current resources of the document team and hard-to-have
> > contributions, it would take years to make that 500 page to have
> > a decent Plone documentation - a key for pleasurable developing
> experience.
> > Plone plays corporation game and sacrifies quantity for quality, but it
> > really doesn't have the resources to drive in contributions, especially
> when
> > the popularity of the project is steadily decreasing. Maybe the
> > documentation team would have more fun when there would be some content
> to
> > managent, instead of tossing those deprecated how tos written for Plone
> > 2.0.x around?
> >
> > We all know this is the internets. Wikis have ~1000:1 (or something)
> > contribution rate against closed gate systems
> > (http://www.kuro5hin.org/story/2001/7/25/103136/121). No matter how many
> > sprints or meetings the doc team has, no matter how many new processes
> it
> > invents, it can't solve the problem of quantity.
> >
> > So, why are you holding back - just wikify the documentation?
> >
> > Just my two cents,
> > Mikko
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > --
> > View this message in context: http://n2.nabble.com/Plone.org-
> documentation-process-considered-harmful-tp1483044p1483044.html
> > Sent from the Documentation Team mailing list archive at Nabble.com.
> >
> >
> > ------------------------------------------------------------------------
> -
> > This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> > Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> > Grand prize is a trip for two to an Open Source event anywhere in the
> world
> > http://moblin-contest.org/redirect.php?banner_id=100&url=/
> > _______________________________________________
> > Plone-docs mailing list
> > [hidden email]
> > https://lists.sourceforge.net/lists/listinfo/plone-docs
> >
>
>
>
> --
>
> Steve McMahon
> Reid-McMahon, LLC
> [hidden email]
> [hidden email]
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
> world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Ricardo Newbery-2]

On Nov 12, 2008, at 1:37 PM, Dylan Jay wrote:

> I'd see something more like this
>
> Plone.org/docs/user -> doc team stuff
> Plone.org/docs/dev/manual -> sphnix
> Plone.org/docs/dev/faq -> open editing with email notifications
> Plone.org/products -> PSC which would have its own docs per product
>
> I'm not sure where or how integrator documentation differs from  
> developer
> documentation since its all about working with the core code.  
> Perhaps there
> is scope to separate theming out from developer docs??

Just a side comment...

I'm guessing the doc team has already thought about this but hopefully  
we can avoid breaking existing links from external sources.  If  
documents are moved, consolidated, or deleted, can we install a  
redirect to the new location or perhaps leave a placeholder describing  
what happened to the original along with some suggested alternatives?

Ric



-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

Ok so we're talking about a lot of ideas here and throwing around a
lot of Ifs and Maybes.

I've created a section in the doc team wiki to help us document various ideas.

http://www.openplans.org/projects/plone-documentation/reorganizing-documentation

Please capture your thoughts here on how you think documents for Plone
should be handled. Any and all ideas are welcome. This is just a place
to capture them all in one spot. We can then go back and analyze
things and find the best solution.

A few loose guidelines for your ideas....
-Plone docs benefit the entire Plone community. Keep all audiences in
mind when proposing your ideas. If you don't know about a certain
audience or only care about a certain audience, please indicate as
such. But please at least try to consider everyone in your solution.
- Play nice with one another. At this point we are not discounting any
ideas. We may not agree with one another but at this point lets just
get some structure to these ideas and worry about debating later.
- Keep it un-biased. Give us as much of a purely factual account of
your idea as possible. Let the idea speak for itself. In other words,
don't persuade us (just yet). Keep it a simple outline of the idea. If
you want to list pros and cons, go ahead...just try to give the team
as accurate of an idea as possible.

oh, and put your name on your idea so we know who to ask about what ideas.

Go forth and brainstorm!
JoAnna

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

> -----Original Message-----
> From: JoAnna Springsteen [mailto:[hidden email]]
> Sent: Thursday, 13 November 2008 10:33 AM
> To: Plone Docs List
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
> Ok so we're talking about a lot of ideas here and throwing around a
> lot of Ifs and Maybes.
>
> I've created a section in the doc team wiki to help us document various
> ideas.
>
> http://www.openplans.org/projects/plone-documentation/reorganizing-
> documentation
>
> Please capture your thoughts here on how you think documents for Plone
> should be handled. Any and all ideas are welcome. This is just a place
> to capture them all in one spot. We can then go back and analyze
> things and find the best solution.
>
> A few loose guidelines for your ideas....
> -Plone docs benefit the entire Plone community. Keep all audiences in
> mind when proposing your ideas. If you don't know about a certain
> audience or only care about a certain audience, please indicate as
> such. But please at least try to consider everyone in your solution.
> - Play nice with one another. At this point we are not discounting any
> ideas. We may not agree with one another but at this point lets just
> get some structure to these ideas and worry about debating later.
> - Keep it un-biased. Give us as much of a purely factual account of
> your idea as possible. Let the idea speak for itself. In other words,
> don't persuade us (just yet). Keep it a simple outline of the idea. If
> you want to list pros and cons, go ahead...just try to give the team
> as accurate of an idea as possible.
>
> oh, and put your name on your idea so we know who to ask about what ideas.
>
> Go forth and brainstorm!

I put the following option on there

---------

Option 1: community - official split documentation

Have have four main areas of the docs and under each have a core set of docs
which are "official" and another set which are community.

   1. Basic use
         1. official plone users manual
         2. open editing howtos and faq
   2. installation and config
         1. official plone installation and config manual
         2. open editing howtos and faq
   3. themeing
         1. official plone theming manual
         2. open editing howtos and faq
   4. development and customisation
         1. offcial plone developing for plone manual -> stored in svn,
complied using sphinx, published on plone.org and made to look like part of
the PHC
         2. open editing howtos and faq - for all the edge cases, and
comparisons between different add ons and methods of developing

Open editing sections have tags which represent categories which are
controled by the doc team. Initial postings are reviewed by the doc team to
give it tags and make sure the title etc is right. After that any registered
member can edit community open editing docs.

If possible there should also be email subscription so anychanges to
community docs could be sent to me if I choose (pbwiki changebot is a good
example of this).

-----

On a related note, it would be very nice if openplans had email notification
of changes to the wiki.



-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Steve McMahon]

On Wed, Nov 12, 2008 at 11:57 AM, Ricardo Newbery
<[hidden email]> wrote:
> ...
> What is it about a wiki that appeals to you in this case?
> ...

Frankly, I don't care about wiki semantics, and think that
hierarchical information layout is usually more navigable than
cobwebbed wiki style.

The key thing is that any member of the community be able to originate
and edit, and that we've got versioning support so that you can see
who changed what. We could do this with unaltered Plone 3.

I'd also like to see us get a terms of use together that will allow us
to really say that all this is CC licensed.

Steve

--

Steve McMahon
Reid-McMahon, LLC
[hidden email]
[hidden email]

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Steve McMahon]

On Wed, Nov 12, 2008 at 1:37 PM, Dylan Jay <[hidden email]> wrote:
> ...
> +1 to all the above except that I think "developing with Plone" could be
> done in svn and sphinx and then republished back into the
> Plone.org/documentation space.
> ...

Developer documentation cannot, and should not, be reduced to modular
API documentation (though modular API documentation is important).
Some of it is about practices, conventions, idioms, and even -- in the
case of the core developers' manual -- community decision making. That
part's narrative, and won't even necessarily be maintained by core
developers themselves.


--

Steve McMahon
Reid-McMahon, LLC
[hidden email]
[hidden email]

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Wichert Akkerman]

Previously Steve McMahon wrote:
> On Wed, Nov 12, 2008 at 1:37 PM, Dylan Jay <[hidden email]> wrote:
> > ...
> > +1 to all the above except that I think "developing with Plone" could be
> > done in svn and sphinx and then republished back into the
> > Plone.org/documentation space.
> > ...
>
> Developer documentation cannot, and should not, be reduced to modular
> API documentation (though modular API documentation is important).

However reference documentation should.

Wichert.

--
Wichert Akkerman <[hidden email]>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

Wichert Akkerman wrote:

> Developer documentation cannot, and should not, be reduced to modular
> API documentation (though modular API documentation is important).

However reference documentation should.

Wichert.

Related to this... any idea how to generate API docs for the "special" technologies we are using

* TAL

* TALES

* METAL

* GenericSetup XML

* ZCML

* .metadata

* All expression contexts (CSS, Javascript, etc. condititions)

Suggestions:

- hints in source code comments, picked up by Sphinx

- Wiki

For Wiki example, see Facebook:

http://wiki.developers.facebook.com/index.php/FBML

they are doing well with normal Wiki.

If possible some kind of "hybrid"  would be great where you can generate API reference documentation from the source, but update/comment ti through-the-web without the pain of register/SVN checkout/commit cycle.

[Mikko Ohtamaa]

Mikko Ohtamaa wrote:

* TAL

* TALES

* ...

Let me add few more

* Views

* Viewlets

* CSS classes and ids

* Page template files

* DTML

* base_properties.prop

[Dylan Jay-4]

> -----Original Message-----
> From: Steve McMahon [mailto:[hidden email]]
> Sent: Friday, 14 November 2008 1:08 PM
> To: Ricardo Newbery
> Cc: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
> On Wed, Nov 12, 2008 at 11:57 AM, Ricardo Newbery
> <[hidden email]> wrote:
> > ...
> > What is it about a wiki that appeals to you in this case?
> > ...
>
> Frankly, I don't care about wiki semantics, and think that
> hierarchical information layout is usually more navigable than
> cobwebbed wiki style.
>
> The key thing is that any member of the community be able to originate
> and edit, and that we've got versioning support so that you can see
> who changed what. We could do this with unaltered Plone 3.
>
> I'd also like to see us get a terms of use together that will allow us
> to really say that all this is CC licensed.

+1 to all that.

I'd just add the email notifications as well. And that can be done with the
subscription plugin.



-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

> -----Original Message-----
> From: Steve McMahon [mailto:[hidden email]]
> Sent: Friday, 14 November 2008 1:17 PM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
> On Wed, Nov 12, 2008 at 1:37 PM, Dylan Jay <[hidden email]> wrote:
> > ...
> > +1 to all the above except that I think "developing with Plone" could be
> > done in svn and sphinx and then republished back into the
> > Plone.org/documentation space.
> > ...
>
> Developer documentation cannot, and should not, be reduced to modular
> API documentation (though modular API documentation is important).
> Some of it is about practices, conventions, idioms, and even -- in the
> case of the core developers' manual -- community decision making. That
> part's narrative, and won't even necessarily be maintained by core
> developers themselves.

+1 very much agrees.

But sphinx is not about api documentation.

The question is, is it better to put the narrative part in svn in the
collective or in Plone?



-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

These are the sort of things that are going into sphinx documentation at the
moment.

Rok has done a fantastic job of showing you can automate some of it, for
instance he's written code that autogenerates documentation of the ATCT
schemas
http://docs.garbas.si/plone-latest/content-types.html

but much won't be able to be autogenerated. And if we can't get it out of
the code anyone can just go edit it now in the collective.

http://dev.plone.org/collective/browser/collective.sphinx.plonedocs/trunk/

It's open for editing.

All you need to know is rst and buildout if you want to compile it.

You're list is fantastic by the way.

> -----Original Message-----
> From: Mikko Ohtamaa [mailto:[hidden email]]
> Sent: Friday, 14 November 2008 10:08 PM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation: first do no harm
>
>
>
>
> Wichert Akkerman wrote:
> >
> >> Developer documentation cannot, and should not, be reduced to modular
> >> API documentation (though modular API documentation is important).
> >
> > However reference documentation should.
> >
> > Wichert.
> >
>
>
> Related to this... any idea how to generate API docs for the "special"
> technologies we are using
>
> * TAL
>
> * TALES
>
> * METAL
>
> * GenericSetup XML
>
> * ZCML
>
> * .metadata
>
> * All expression contexts (CSS, Javascript, etc. condititions)
>
> Suggestions:
>
> - hints in source code comments, picked up by Sphinx
>
> - Wiki
>
> For Wiki example, see Facebook:
>
> http://wiki.developers.facebook.com/index.php/FBML
>
> they are doing well with normal Wiki.
>
> If possible some kind of "hybrid"  would be great where you can generate
> API
> reference documentation from the source, but update/comment ti
> through-the-web without the pain of register/SVN checkout/commit cycle.
> --
> View this message in context: http://n2.nabble.com/Plone.org-
> documentation%3A-first-do-no-harm-tp1490526p1498015.html
> Sent from the Documentation Team mailing list archive at Nabble.com.
>
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
> world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs