Plone.org documentation process considered harmful

[Mikko Ohtamaa]

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









 

[Dylan Jay-4]

Hi Mikko,

I could agree with you more except for the completely unstructured wiki. I
will explain below.

I see two things solving most of these problems.

Instant edit FAQ and sphinx based developer reference manual.

Togeather this gives two places to document both with more open access than
there is currently.
Those two places have very little cross over. The developers reference
manual covers core Plone and how to work with it and its api. It won't try
to cover all the different ways of working with it or all the ways it can be
used.

The FAQ would cover the more practical things like "how to create a splash
screen" or "how do I enable email notifications of changes" or "how do I
integrate with windows SSO" etc. That's where the solutions to problems that
take each of us 12 hours to research can get put. And they don't have to be
complete answers; others can jump in and improve them or add links to better
documentation or blog entries.


Sphinx based developer reference manual
=======================================
Sphinx doesn't solve the problem of the missing documentation but it creates
a place for it. I'm currently putting in a chapter structure in that
highlights exactly what is missing. We can then repurpose existing docs to
fill some of those spots (with permission). It will take time to complete
but we won't wait for it to be complete to release it.

Next thing is that it will be open documentation development probably in the
collective. Anyone who wants to see whats being worked on can.

Also it should encourage module developers to include better documentation
if they know its going to be bundled into a publicly available developers
reference manual.

Instant edit FAQ
================
I don't think an open structured wiki is good as its too open to having a
confusing and tangled structure.
But we need a quick way to contribute the tips and tricks and howto solves
specific problems with Plone type information, just has you have
highlighted.

My proposal is to take the existing FAQ and open up access with rules
similar to what has been done with kaizenplone.org.
Those rules are
- Pages are titled with a problem statement or question
- description or first section is a more fuller description of the problem
without any description of the solution.
- The addition of a new page is a gateway review process to ensure there are
no duplicate pages and the above happens.
- The contents of the page includes one section per different way to solve
the problem each with pros and cons. The page is then a continuous shootout
of the different solutions. This solves the problem of finding different
ways to do something in different places and not knowing if one superceeds
the other etc.
- The page updates are sent to those who have nominated themselves to watch
the page. If they don't like the changes they can update it again. No
gateway review process.

Would these together solve your pain?


Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:[phone] ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341

> -----Original Message-----
> From: Mikko Ohtamaa [mailto:[hidden email]]
> Sent: Tuesday, 11 November 2008 11:23 AM
> To: [hidden email]
> Subject: [Plone-docs] Plone.org documentation process considered harmful
>
>
> 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

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

> The problem with Plone documentation is not quality, it's quantity.

I respectfully and fervently disagree. We have almost 2000 documents
contained in the documentation section of Plone.org. I'd venture a
guess and say that about half of them are unusable because they are
not quality documents.  Yes, some topics are not documented. We are
identifying those and finding people to write them.
Of course if we had 10,000 documents you'd be writing to complain how
you can't find anything you need. It's two sides of the same coin.
Those of us that actively participate in the doc team on a regular
basis have gone round and round on this topic. We're in agreement that
fewer, higher quality documents is a better approach. No, we're not
there yet, but we're working on 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.

Figuring out how to add docs to plone.org is a bit tough at the
moment. Hopefully with the newly redesigned plone.org, we will see
that become easier. If it's not part of the design, we will fix it.
We're in limbo right now and not making changes to plone.org in its
current state.
As for asking in IRC...well get a doc team member. #plone-docs is a
good channel to ask such things in. Or the mailing list. That's what
it's for.
As for logging in, well, plone.org is a content management system. If
that bothers you, you're working on the wrong project.

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

The doc team is very good about working with people who submit things
to make sure that they are accurate when published. We're also pretty
picky about publishing docs that illustrate good techniques...maybe
not best practices but definitely things that aren't going to hurt you
in the long run. If you don't want to make suggested changes, that's
fine. You can either let a doc team member make those changes and then
publish the doc or scrap it all together. We understand not everyone
has time to make docs perfect. Many people ask people to help
collaborate on the doc list or in #plone-docs. But you have to make
the effort to ask.

> plone.org documentation process is too rigid and currently needs heroic
> individuals to make anything show up there.

Again, I disagree. We have people submitting documents all the time.
It's not a heroic effort. If someone choses to submit a doc, that
individual has to take the time to see the process through.


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

Uh no. We work together as a team. We help each other. Take a look at
some of our bigger manuals and look at all the contributors involved
on them. We work together on these things, edit one another's work.
Writing is a process. It's a different kind of process that many
programmers aren't used to. It takes time and yes it is involved. But
that doesn't mean the process is a bad process.

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

Not gonna happen. Wikis are anti-document management and a mess to
maintain. Once apon a time, plone docs use to be like that. There was
a decision made somewhere along the way to move away from that. You'd
probably have to ask Limi for more details but I'm sure there are
definite reasons on why this didn't work out.


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

At the risk of sounding like a smart ass but we've had several people
publish books on Plone that are over 500 pages and that took a year or
less to write. The latest, about to be released, Plone book was
written by many different contributors, has taken just about a year,
and, from what I've seen, is more than decent.
Writing is not a heroic effort. People just need to suck it up and do
it. I'm hard pressed to feel sorry for those who complain about a lack
of documentation but don't step up and pitch in any way they can. This
is an open source community. Things only exist if the community
pitches in to get things done. That goes for tasks outside of writing
code.


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

I'm confused. You've stated that you're not an active follower of
Plone documentation project yet you're comfortable enough to make
claims about our resources? Perhaps you should avoid doing so until
you're fully aware of all the things the team is working on.

 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?

Again, this statement makes it obvious to me that you are not aware of
what the Plone doc team actually does. Are you aware of the great
strides the team has made in the past year? Do you know what we do on
a regular basis? Me thinks not.

 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?

Quantity isn't necessarily the issue. Quality is. I've seen what our
doc team can accomplish in just one sprint, and yes, we can solve our
issues. We are only human and only have so much time. We're
volunteers. Things take time. It helps us tremendously when people
step up and volunteer to help to actually do some writing. I'll tell
you the same thing I tell everyone else when they whine...it's your
project too. Get your hands dirty and get in here and do something to
make it better.

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

[Anne Bowtell]

I get worried that we're all talking at cross-purposes. "Documentation"
seems to me to cover a multitude of things:

* things that document - like a developer's API

* things that guide you - like How Tos or Tutorials or FAQs

* things that introduce you

and we have two audiences - those that are just starting out and those
that are already deep into Plone.

If you're just starting out (and I know this because this encompasses a
number of my colleagues, both developers and integrators), then you want
above all, a clear answer to the basics and consistency. I think this is
a good argument for some streamlined, well-written, well-edited core
guides and overviews.

When you're deep into Plone you want the ability to delve deeper for an
edge case, get some help with deciding which route to take and to be
able to contribute back - quickly, with the minimum of fuss. I think
this is a good argument for a Wiki - for all its possible faults.

Right at the moment, we have a monster which is somewhere between the
two (and frankly scares my newbie colleagues off). It is too big for
consistency and editorial overview, but not flexible enough to be a real
Wiki. It is created and curated by people who are really good at what
they do and really care; but I think we should let it out of its cage
and into the community.

In its place, I think we should use the incredible talents we have to
create a framework for taming a much sleaker beast, with clear direction
and focus, consistency and editorial standards - but an animal that we
know we can continue to take care of (that will enable us to match our
expectations with our resources).


Anne

(and I also think that as web professionals, we should be seriously
looking at new ways of aggregating scattered documentation across the
www - but that's another story)


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

[Graham Perrin]

Mikko Ohtamaa wrote:

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

Very nearly +1 to that, but I wonder whether the underlying issue is that *expressions of procedure* could be better.

_Expressions_ and process relating to Framework Team are certainly improving, <http://dev.plone.org/plone.org/ticket/756> and <http://dev.plone.org/plone/ticket/7816> respectively … and I imagine that the *expression* of Plone documentation-related procedures may be reviewed in due course.

(AFAIK most barriers or obstacles that affect me are to be phased out, before long; or may gain suitable workarounds.)

A Bowtell wrote:

… as web professionals, we should be seriously looking at new ways of aggregating scattered documentation across the www - but that's another story …

+1 to that and FYI,
<http://n2.nabble.com/Distributed-Documentation--tp359835p359837.html> — I'll add to that thread very soon.

[Mikko Ohtamaa]

>Of course if we had 10,000 documents you'd be writing to complain how
>you can't find anything you need. It's two sides of the same coin.
>Those of us that actively participate in the doc team on a regular
>basis have gone round and round on this topic. We're in agreement that
>fewer, higher quality documents is a better approach. No, we're not
>there yet, but we're working on it.

I am not complaining that I don't find what I need. You can't find something that does not exist.

I am complaining that if there are uncovered answers it should be made easy for developers to cover them. Your answer grasps the spirit of Plone documentation seen as from the external developer eyes very well.

"I have solved this problem and this answer would benefit all Plone developers"

"We don't need your stinking doc. Go to fsck yourself."

So if you are not giving me a place to publish my how tos, then who is? Should everyone start from the scratch when solving the same problem becausePlone documentation team hasn't had resources to cover the issue? Wiki / Instant edit FAQ (I'd rather call it wiki) as proposed earlier would solve this problem. Areas of wiki are purposefully for advanced developers, so that Joe the Ploner spots it when he accidentally tumbles in to stuff which goes way above his head. Think Facebook users and developers.facebook.com - the former never need the latter, but there is some point for it to exist...

> Sphinx doesn't solve the problem of the missing documentation but it creates
> a place for it. I'm currently putting in a chapter structure in that
> highlights exactly what is missing. We can then repurpose existing docs to
> fill some of those spots (with permission). It will take time to complete
> but we won't wait for it to be complete to release it.

Indeed Sphinx doesn't solve the problem of the missing documetation. Most of Plone classes are basically commentless. But maybe we could create a medium where the developers itself could contribute to the documentation somehow?

It is simple.

Let's take the most horrible web development thingy invited by the man. It has horrible, buggy, API. But somehow people have managed to come around with it. One example:

http://docs.php.net/manual/en/function.print-r.php

So if there is a Sphinx documentation I absolutely demand commenting feature on it. Documentation will surely be held back if you need to have a signed agreement and SVN acces to contribute for it.

 
> Not gonna happen. Wikis are anti-document management and a mess to
> maintain. Once apon a time, plone docs use to be like that. There was
> a decision made somewhere along the way to move away from that. You'd
> probably have to ask Limi for more details but I'm sure there are
> definite reasons on why this didn't work out.

Maybe you should reconsider your position - the document team might have been out of touch with low to mid level Plone developers. We are thinking apples and oranges here. I might not know what doc team does, but obviously doc team doesn't always know what concerns an average Plone developer either - the reason I posted my rant before and it obviously landed to its goal. So please do not take my message as an hostile attempt to nullify your great work - we are all in the same community boat here and we all want to see Plone to success. We just have different perspectives and different problems.

Cheers,
Mikko

[Graham Perrin]

@ Mikko

You are very welcome to join me at
<http://groups.diigo.com/groups/ploned> -- OpenID accepted, including Google OpenID. From this vantage point we gain the ability to highlight, comment and apply sticky notes to very nearly any web page. I will be more than happy to guide you.

Best regards
Graham

[Rok Garbas]

On Wed, Nov 12, 2008 at 1:10 AM, Mikko Ohtamaa
<[hidden email]> wrote:

>> Sphinx doesn't solve the problem of the missing documentation but it
>> creates
>> a place for it. I'm currently putting in a chapter structure in that
>> highlights exactly what is missing. We can then repurpose existing docs to
>> fill some of those spots (with permission). It will take time to complete
>> but we won't wait for it to be complete to release it.
>
> Indeed Sphinx doesn't solve the problem of the missing documetation. Most of
> Plone classes are basically commentless. But maybe we could create a medium
> where the developers itself could contribute to the documentation somehow?
>
> It is simple.
>
> Let's take the most horrible web development thingy invited by the man. It
> has horrible, buggy, API. But somehow people have managed to come around
> with it. One example:
>
> http://docs.php.net/manual/en/function.print-r.php

i just post on this subject
http://sharbas.blogspot.com/2008/11/one-week-of-riding-sphinx.html

and i'm already looking into commenting tool that we could use with
sphinx. did look much around but it smells something like wsgi
middleware. i hope we could reuse some already existing one or create
our own.

now that sphixbuilder is ready, and collective.sphinx.plonedocs
buildout working you can checkout and try it. if you need some guide
just drop a mail to me or ask around.



--
Rok Garbas
http://sharbas.blogspot.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

[Dylan Jay-4]

> -----Original Message-----
> From: Mikko Ohtamaa [mailto:[hidden email]]
> Sent: Wednesday, 12 November 2008 11:11 AM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation process considered
> harmful
>
>
> >Of course if we had 10,000 documents you'd be writing to complain how
> >you can't find anything you need. It's two sides of the same coin.
> >Those of us that actively participate in the doc team on a regular
> >basis have gone round and round on this topic. We're in agreement that
> >fewer, higher quality documents is a better approach. No, we're not
> >there yet, but we're working on it.
>
> I am not complaining that I don't find what I need. You can't find
> something
> that does not exist.
>
> I am complaining that if there are uncovered answers it should be made
> easy
> for developers to cover them. Your answer grasps the spirit of Plone
> documentation seen as from the external developer eyes very well.
>
> "I have solved this problem and this answer would benefit all Plone
> developers"
>

+1

It's for these reason I think fixing the "process" is not enough as was
mentioned.
The psychology of the current Plone.org tutorials etc are not working.
They are created by an author and therefore owned by that author. If someone
sees something wrong with it they don't feel its their place to edit it, and
in fact can't even if they wanted to. They might in some cases comment on it
but then the there is every likelihood of those comments not getting
factored back in.
Then when wanted to add new docs the formality is psychological barrier even
aside from the lag in review time.
Third point is that people feel the need to create specific howtos "how to
use buildout on windows with svn using eclipse as your test editor". You
then get 10 documents all covering roughly the same area in different ways.
Since 1 person is responsible for the entire connent they don't feel expert
enough in creating a more general subject. If they knew others would own it
to and add more later they might feel more comfortable.

For all these reasons I'm all for open editing and multiple authors in parts
of the docs.

> So if you are not giving me a place to publish my how tos, then who is?
> Should everyone start from the scratch when solving the same problem
> becausePlone documentation team hasn't had resources to cover the issue?
> Wiki / Instant edit FAQ (I'd rather call it wiki) as proposed earlier

The reason I didn't call it a wiki is because Joanna has a misconception of
the concept of a wiki. A misconception she is very apposed to.
Wikis aren't anti-document management Joanna. They don't have to be
unstructured. Wikis are 3 concepts combined together and we don't have to
take onboard all of them at once.
We can have a more well defined structure but still have open editing. It's
as simple has having a workflow that allows all members to edit. And instead
of a review step you have email notification of changes so those interested
can review it later rather than as in a "dictatorial" style. There are many
different forms of content management each has their pros and cons.
I agree 100% that open editing is needed.

> would
> solve this problem. Areas of wiki are purposefully for advanced
> developers,
> so that Joe the Ploner spots it when he accidentally tumbles in to stuff
> which goes way above his head. Think Facebook users and
> developers.facebook.com - the former never need the latter, but there is
> some point for it to exist...
>
> > Sphinx doesn't solve the problem of the missing documentation but it
> > creates
> > a place for it. I'm currently putting in a chapter structure in that
> > highlights exactly what is missing. We can then repurpose existing docs
> to
> > fill some of those spots (with permission). It will take time to
> complete
> > but we won't wait for it to be complete to release it.
>
> Indeed Sphinx doesn't solve the problem of the missing documetation. Most
> of
> Plone classes are basically commentless. But maybe we could create a

We're hoping high exposure of what's missing combined with some development
documentation sprints will get the ball rolling on developers documenting
the modules along with the code.

> medium
> where the developers itself could contribute to the documentation somehow?
>
> It is simple.
>
> Let's take the most horrible web development thingy invited by the man. It
> has horrible, buggy, API. But somehow people have managed to come around
> with it. One example:
>
> http://docs.php.net/manual/en/function.print-r.php
>
> So if there is a Sphinx documentation I absolutely demand commenting
> feature
> on it. Documentation will surely be held back if you need to have a signed
> agreement and SVN acces to contribute for it.

Before I responding to commenting, lets look how sphinx will actually work.

The documents will be in 2 places. Part will be in the collective which
requires no signed agreement. Part will be with the modules themselves which
will require a signed agreement.
However the great thing about sphinx is it lets you create one cohesive
document from rst files from very different places.
If a developer want to improve the documentation they could do it completely
in the collective based docs. All they need is svn access to the collective.
If they don't have that then they aren't really a developer are they?
Alternatively we already have a commenting and patching feature for whats in
svn, its called trac. We can link to that so that if you don't want to
directly update the docs you can do so via trac, including submitting
patches.

I realise the UI might not be as nice but I think that keeping the process
as close to what developers currently use will have more benefit than
outweighs the disadvantages.

 

>
> > Not gonna happen. Wikis are anti-document management and a mess to
> > maintain. Once apon a time, plone docs use to be like that. There was
> > a decision made somewhere along the way to move away from that. You'd
> > probably have to ask Limi for more details but I'm sure there are
> > definite reasons on why this didn't work out.
>
> Maybe you should reconsider your position - the document team might have
> been out of touch with low to mid level Plone developers. We are thinking
> apples and oranges here. I might not know what doc team does, but
> obviously
> doc team doesn't always know what concerns an average Plone developer
> either
> - the reason I posted my rant before and it obviously landed to its goal.
> So
> please do not take my message as an hostile attempt to nullify your great
> work - we are all in the same community boat here and we all want to see
> Plone to success. We just have different perspectives and different
> problems.

My suggestion is to join http://www.openplans.org/projects/plonedevdocs/team
This group was specifically setup to improve developer documentation in new
and different ways with the goal of merging them with the official Plone
documentation area if they prove successful.
Open source is all about open approaches and the best ways will win out in
the end in my opinion.
If you're a developer and passionate about this then we can always do with
more hands.

> Cheers,
> Mikko
> --
> View this message in context: http://n2.nabble.com/Plone.org-
> documentation-process-considered-harmful-tp1483044p1487625.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

[vedaw]

Regarding Sphinx, if you're going to spend time working on this, let's make
sure you get the buy in from the rest of the development community before
going too much further.

Do you think you're ready for that? Would it be worthwhile to set up a
SurveyMonkey survey or something similar to collect opinions in a
quantifiable fashion?

- Veda


On 11/11/08 7:14 PM, "Dylan Jay" <[hidden email]> wrote:


> My suggestion is to join http://www.openplans.org/projects/plonedevdocs/team
> This group was specifically setup to improve developer documentation in new
> and different ways with the goal of merging them with the official Plone
> documentation area if they prove successful.



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

[Rok Garbas]

On Wed, Nov 12, 2008 at 4:22 AM, Veda Williams <[hidden email]> wrote:
> Regarding Sphinx, if you're going to spend time working on this, let's make
> sure you get the buy in from the rest of the development community before
> going too much further.
>

we are just finishing it. lots of companies use it for documenting
internal stuff. all that was developed was openly accepted into
sphinx. i think includedoc directive will also make it to sphinx core.
so development wont got to nothing.

> Do you think you're ready for that? Would it be worthwhile to set up a
> SurveyMonkey survey or something similar to collect opinions in a
> quantifiable fashion?
>

survey monkey is not the way to go here. at least not at this point.
now that we have something to show will go with what we have to
plone-developers list and get feedback. most of developers are trilled
to see this happening, all of them heard lots of good things about
sphinx and also bad. i'm expecting big debate on this topic (well at
least i'm hoping to) since most of the work will be done by
developers.

current plan for sphinx is to replace api, pull as many useful
doctests to sphinx and list plone.org tutorials that
could/should/would be in this new api.plone.org (or wherever we will
place it).


--
Rok Garbas
http://sharbas.blogspot.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

[vedaw]

>
> survey monkey is not the way to go here. at least not at this point.
> now that we have something to show will go with what we have to
> plone-developers list and get feedback. most of developers are trilled
> to see this happening, all of them heard lots of good things about
> sphinx and also bad. i'm expecting big debate on this topic (well at
> least i'm hoping to) since most of the work will be done by
> developers.

Yeah, my fear is that the discussion will be large and hard to disseminate,
which is the only reason why I suggested SurveyMonkey to break that down a
little more easily. But, if you're ready for the onslaught (or close), I
look forward to the flurry of emails!

- Veda


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

On Tue, Nov 11, 2008 at 9:45 PM, Veda Williams <[hidden email]> wrote:

>
>>
>> survey monkey is not the way to go here. at least not at this point.
>> now that we have something to show will go with what we have to
>> plone-developers list and get feedback. most of developers are trilled
>> to see this happening, all of them heard lots of good things about
>> sphinx and also bad. i'm expecting big debate on this topic (well at
>> least i'm hoping to) since most of the work will be done by
>> developers.
>
> Yeah, my fear is that the discussion will be large and hard to disseminate,
> which is the only reason why I suggested SurveyMonkey to break that down a
> little more easily. But, if you're ready for the onslaught (or close), I
> look forward to the flurry of emails!

+1 for quantifiable results. anything that can give us hard numbers
over a bunch of different opinions is probably a better way to go. The
discussion needs to happen, but can be interpreted in many different
ways.

-------------------------------------------------------------------------
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: Veda Williams [mailto:[hidden email]]
> Sent: Wednesday, 12 November 2008 2:46 PM
> To: Rok Garbas
> Cc: Dylan Jay; Mikko Ohtamaa; [hidden email];
> [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation process considered
> harmful
>
>
> >
> > survey monkey is not the way to go here. at least not at this point.
> > now that we have something to show will go with what we have to
> > plone-developers list and get feedback. most of developers are trilled
> > to see this happening, all of them heard lots of good things about
> > sphinx and also bad. i'm expecting big debate on this topic (well at
> > least i'm hoping to) since most of the work will be done by
> > developers.
>
> Yeah, my fear is that the discussion will be large and hard to
> disseminate,
> which is the only reason why I suggested SurveyMonkey to break that down a
> little more easily. But, if you're ready for the onslaught (or close), I
> look forward to the flurry of emails!

The result of votes can be misleading as it can be the perception on just
what was presented rather truthful content. We can put the wrong idea of
what sphinx based docs would be like and turn everyone off it from the
start.

For this reason we are trying to get it right.

What we're debating now is this:

Should it be either

a) just purely a replacement for api docs and not include any cross-module
documentation?

b) have empty chapters showing an example of how it could be organised to be
a more full reference manual capable of containing large amounts of the
developer tutorials on Plone.org.

Both have its pros and cons.



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

I'll trust you guys to know best here, since only you know the kind of
feedback you're trying to get.

- Veda  

> The result of votes can be misleading as it can be the perception on just
> what was presented rather truthful content. We can put the wrong idea of
> what sphinx based docs would be like and turn everyone off it from the
> start.
>
> For this reason we are trying to get it right.
>
> What we're debating now is this:
>
> Should it be either
>
> a) just purely a replacement for api docs and not include any cross-module
> documentation?
>
> b) have empty chapters showing an example of how it could be organised to be
> a more full reference manual capable of containing large amounts of the
> developer tutorials on Plone.org.
>
> Both have its pros and cons.
>
>

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

My two cents...

First of all, I suspect my thoughts on this are not really new to the  
doc team so forgive me if this has already be debated to death.  :-)

I agree that community wiki's are a mess to maintain.  Wikipedia seems  
to work mostly because of the shear volume of editors battling it  
out.  The only good community wiki's I've seen tend to be either the  
product of a small close-knit group or the product of a larger group  
that is managed by some brutal editorial process.  Even if we were  
able to recruit enough editors per document to approach Wikipedia-like  
coverage, I fear that the near anarchistic pugilistic editorial  
process that it encourages is probably not something that we would be  
comfortable with in the long run.

I realize that it's probably a work in progress but I personally  
haven't found efforts like kaisenplone.org to be terribly useful.  And  
I'm skeptical of any automated documentation effort... I just don't  
find api.plone.org useful and doubt that sphinx will improve it that  
much... but I would be very happy to be proven wrong.

I do think there might be some benefit to figuring out how to relax  
the current doc ownership situation.  Perhaps all docs should be  
"owned" by the doc team with an easier path for multiple contributors  
to pitch in, while still keeping it under the editorial control of the  
doc team.  We should be able to figure out a workflow to allow this.  
Note: I have to sheepishly admit that I have no idea if this is really  
necessary, having never offered to fix a broken doc myself -- am I  
suggesting a fix for a problem that doesn't really exist?   ;-)

I also agree that we have some significant blind spots in our  
available documentation but we also have a more serious problem with  
the volume of outdated (or just plain wrong) documentation, which  
since it's found on plone.org, appears to the newbie to have the  
imprimatur of the Plone community.  Attempting to fix the first  
problem without addressing the second does not seem likely to improve  
the overall situation.

Good documentation is nearly as important as good software.  Just as  
there is a process to review, revise, or discard, contributions to the  
Plone core software, it makes sense that there should be a process to  
review, revise, or discard contributions to the documentation on  
plone.org.

The current documentation sometimes frustrates me.  Sometimes I'm  
annoyed at the many "little" docs that waste my time and the shortage  
of enough "big picture" docs that cover the fundamentals I need at the  
moment.  But occasionally, one of those little docs pops up in google  
search and saves me from an all-nighter trying to figure it out on my  
own.  Some of the docs are not terribly useful but even the good bits  
often could use some consolidation.  Do we really need 5+ tutorials/
how-to's on how to configure Apache with Plone?   Or five how-to's on  
proxy caching?

I truly do appreciate the "little" docs and the edge case how-to's but  
if they can't be folded into a more general doc, do they really need  
to be on plone.org?  Not everyone will feel comfortable with the  
editorial process and not everything should necessarily be crammed  
into this space.  Plone.org is not now and will probably never be the  
sole source for all answers to our Plone questions.

Perhaps it might be better to include more information about the Plone  
community outside of Plone.org and provide links to alternative  
documentation sources and community search engines.  Probably no-one  
wants to manually maintain a directory of external sources but we  
already have four great meta-sources that potentially can be used to  
feed to a community-wide search engine: the Plone and Zope support  
forums, the blogs listed on planet.plone.org (why is there no  
prominent link to this resource from plone.org?), and the list of  
providers on plone.net.

We don't have such a community-wide search yet (unless you count  
Google) but perhaps something like the following links could be  
included on the main documentation page under Additional Resources...

To search Plone support forums:
http://plone.org/support/forums

To search Zope support forums:
http://www.nabble.com/Zope-f6706.html

An experimental Plone community search (does not include the support  
forums above):
http://www.google.com/coop/cse?cx=005073405052215111557%3An2qqdxewyaa

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]

> I agree that community wiki's are a mess to maintain.  Wikipedia seems
> to work mostly because of the shear volume of editors battling it
> out.  The only good community wiki's I've seen tend to be either the
> product of a small close-knit group or the product of a larger group
> that is managed by some brutal editorial process.  Even if we were
> able to recruit enough editors per document to approach Wikipedia-like
> coverage, I fear that the near anarchistic pugilistic editorial
> process that it encourages is probably not something that we would be
> comfortable with in the long run.

+1

> I realize that it's probably a work in progress but I personally
> haven't found efforts like kaisenplone.org to be terribly useful.  And
> I'm skeptical of any automated documentation effort... I just don't
> find api.plone.org useful and doubt that sphinx will improve it that
> much... but I would be very happy to be proven wrong.

kaizenplone has yet to really fully manifest so it's hard to say what
it will or won't be.
As for using sphinx to document our API...well it's still only as good
as what developers put in the API. If people aren't documenting their
code then it won't be in there. Sphinx makes it look a lot nicer than
the old api.plone.org, that's for sure. But until people change their
habits and make documentation a priority, it's not going to help too
much.


> I do think there might be some benefit to figuring out how to relax
> the current doc ownership situation.  Perhaps all docs should be
> "owned" by the doc team with an easier path for multiple contributors
> to pitch in, while still keeping it under the editorial control of the
> doc team.  We should be able to figure out a workflow to allow this.
> Note: I have to sheepishly admit that I have no idea if this is really
> necessary, having never offered to fix a broken doc myself -- am I
> suggesting a fix for a problem that doesn't really exist?   ;-)

A note on doc ownership: if you'll notice in the footer of each doc in
the doc section it says "All content is copyright Plone Foundation and
the individual contributors."
SteveM has been working dilligently to make sure that plone docs are
all switched over to a creative commons license of sorts. Even now
with the Plone Foundation as the "owner"....that's a lot of people
that own that document....not just the original author. Take a look at
the End User manuals. I first wrote a draft in 2005(ish). Look at the
list of collaborators on it now. We've taken content from
learnplone.org and many other people's personal notes and refactored
that manual to be far more robust. I am hearing you guys say that
there is a wall that doesn't all collaboration on docs or multiple
contributors but it just isn't true. We have a long standing process
of incorporating new info into existing docs. We work with the
original author if we can but when push comes to shove, we make the
changes to keep the doc up to date. And this is something we're
constantly doing on either a formal or informal basis. We make changes
as quickly as possible so the process is transparent. Maybe it has
been too transparent...

> I also agree that we have some significant blind spots in our
> available documentation but we also have a more serious problem with
> the volume of outdated (or just plain wrong) documentation, which
> since it's found on plone.org, appears to the newbie to have the
> imprimatur of the Plone community.  Attempting to fix the first
> problem without addressing the second does not seem likely to improve
> the overall situation.

This is the exact reason for the section editors doing their section
assessments. (see the list under topic section assessments if you
aren't familiar:
http://www.openplans.org/projects/plone-documentation/project-home)
We're looking at what we have, evaluating it, and finding out where
the big gaps are. This way we get rid of the outdated, know what we
need to create, and can sleep easy knowing that newbies don't have to
worry about which doc is right for them. We are addressing both
problems because, you're right, doing one with out the other doesn't
get us anywhere.

> Good documentation is nearly as important as good software.  Just as
> there is a process to review, revise, or discard, contributions to the
> Plone core software, it makes sense that there should be a process to
> review, revise, or discard contributions to the documentation on
> plone.org.

Amen. every good doc set has a process.

> The current documentation sometimes frustrates me.  Sometimes I'm
> annoyed at the many "little" docs that waste my time and the shortage
> of enough "big picture" docs that cover the fundamentals I need at the
> moment.  But occasionally, one of those little docs pops up in google
> search and saves me from an all-nighter trying to figure it out on my
> own.  Some of the docs are not terribly useful but even the good bits
> often could use some consolidation.  Do we really need 5+ tutorials/
> how-to's on how to configure Apache with Plone?   Or five how-to's on
> proxy caching?

It frustrates most everyone. Hence the reason we're actively trying to
fix it up. I'm right there with you wondering why we have 5 tutorials
on one subject. I think we need one good one that covers the most
common use case(s) and then can link out to related information at the
end. We can't document every fringe use case, nor should we try to. We
need to make sure our basics are covered before we worry about odd
random things. I'm a firm believer in best practices but I know many
others don't care for that concept. We need to establish, at the very
least, the most common and generally agreed apon practices and
document those on plone.org.


> I truly do appreciate the "little" docs and the edge case how-to's but
> if they can't be folded into a more general doc, do they really need
> to be on plone.org?

The edge case stuff is often the stuff that saves you in your time of
need. But do they need to be on plone.org? probably not. But they need
to exist somewhere. I think a lot of blog posts end up covering this
territory and coming in really handy.


 Not everyone will feel comfortable with the
> editorial process and not everything should necessarily be crammed
> into this space.  Plone.org is not now and will probably never be the
> sole source for all answers to our Plone questions.

As much as I wish it was the sole source for all things Plone, you're
probably right. But it can become a more reliable and accurate source
for documentation.
We've had a lot of talk about having two separate locations for plone
docs. I'm still not sure how I feel about this. I'm not entirely
convinced that this will solve our issues. I'm more worried that it
will create more issues than we have now. It's obvious we need to come
up with some sort of solution soon. It's on our doc team roadmap
(http://www.openplans.org/projects/plone-documentation/doc-team-roadmap)
to address it in the first quarter of 2009. Less than two months
away...We need to start coming up with constructive solutions on how
to address our needs.


> Perhaps it might be better to include more information about the Plone
> community outside of Plone.org and provide links to alternative
> documentation sources and community search engines.  Probably no-one
> wants to manually maintain a directory of external sources but we
> already have four great meta-sources that potentially can be used to
> feed to a community-wide search engine: the Plone and Zope support
> forums, the blogs listed on planet.plone.org (why is there no
> prominent link to this resource from plone.org?), and the list of
> providers on plone.net.

good idea...


> An experimental Plone community search (does not include the support
> forums above):
> http://www.google.com/coop/cse?cx=005073405052215111557%3An2qqdxewyaa

ooooh neato. that would be pretty darn handy wouldn't it...

-------------------------------------------------------------------------
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: Ricardo Newbery [mailto:[hidden email]]
> Sent: Wednesday, 12 November 2008 6:03 PM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation process considered
> harmful
>
>
> My two cents...
>
> First of all, I suspect my thoughts on this are not really new to the
> doc team so forgive me if this has already be debated to death.  :-)
>
> I agree that community wiki's are a mess to maintain.  Wikipedia seems
> to work mostly because of the shear volume of editors battling it

-1.

I think wikipedia works not only because of all the editors but because it
has a clear structure. It's flat. One subject per page. No need for table of
contents or hierarchies. Everyone understands encyclopaedia structures.
What you and joanna both seem to be wary is the lack of structure when users
make the structure of a site as they go. I agree that often leads to bad
results.
But people also understand FAQ structures well. It's also flat. That's why I
think a faq-wiki will work.

> I realize that it's probably a work in progress but I personally
> haven't found efforts like kaisenplone.org to be terribly useful.  And

Of course its not useful. It's not even launched. There is no content on
there. The functionality hasn't been finished. In hindsite I should never
have put it live till it was.
Don't judge it by its content.

> I'm skeptical of any automated documentation effort... I just don't
> find api.plone.org useful and doubt that sphinx will improve it that
> much... but I would be very happy to be proven wrong.

Sphinx effort is NOT about just automated api. It's about put the
documentation that is disorganised and out of date and putting into svn so
developers feel more comfortable updating it. It is also about combining it
with automated documentation to ease the effort involved.
I don't think Plone api by automated docs alone.
 
> own.  Some of the docs are not terribly useful but even the good bits
> often could use some consolidation.  Do we really need 5+ tutorials/
> how-to's on how to configure Apache with Plone?   Or five how-to's on
> proxy caching?

If there was an obvious place for all caching related docs and it was open
for anyone to edit there wouldn't be that problem. The Plone.org docs review
process forces people to create multiple versions if the original is
inadequate.

> I truly do appreciate the "little" docs and the edge case how-to's but
> if they can't be folded into a more general doc, do they really need
> to be on plone.org?  Not everyone will feel comfortable with the

All this folding is currently happening with the new editors I believe. I
think it will help but won't solve the problem long term IMO. Time will
tell.

> editorial process and not everything should necessarily be crammed
> into this space.  Plone.org is not now and will probably never be the
> sole source for all answers to our Plone questions.
 
> Perhaps it might be better to include more information about the Plone
> community outside of Plone.org and provide links to alternative
> documentation sources and community search engines.  Probably no-one
> wants to manually maintain a directory of external sources but we
> already have four great meta-sources that potentially can be used to
> feed to a community-wide search engine: the Plone and Zope support
> forums, the blogs listed on planet.plone.org (why is there no
> prominent link to this resource from plone.org?), and the list of
> providers on plone.net.

The intent behind kaizenplone or any other wiki is to be a repository for
links to the "best" documentation on any subject. An FAQ-wiki would no doubt
work the same.

> We don't have such a community-wide search yet (unless you count
> Google) but perhaps something like the following links could be
> included on the main documentation page under Additional Resources...
>
> To search Plone support forums:
> http://plone.org/support/forums
>
> To search Zope support forums:
> http://www.nabble.com/Zope-f6706.html
>
> An experimental Plone community search (does not include the support
> forums above):
> http://www.google.com/coop/cse?cx=005073405052215111557%3An2qqdxewyaa

Interesting idea.
Doesn't solve the problem of poor search ranking however.
With multiple solutions to any one problem it's hard to know which to trust.
The older the solution is often the more likely to be at the top.
A faq-wiki on Plone.org would help here too since people can point to
answers on the faq, this gives the answers a high ranking over time. yet the
solutions contained in the answer remain up to date. This is especially true
if the url represents the problem as the problem will rarely change but the
solution will over time.

e.g http://www.plone.org/docs/faq/how-do-i-configure-proxy-caching

I think we should just open up the editing on the existing faq to all
members so this can happen.

Actually looking at the all the metadata, in the faq types, it needs more
work than that.



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

> As for using sphinx to document our API...well it's still only as good
> as what developers put in the API. If people aren't documenting their
> code then it won't be in there. Sphinx makes it look a lot nicer than
> the old api.plone.org, that's for sure. But until people change their
> habits and make documentation a priority, it's not going to help too
> much.

Just to be 100% crystal clear: sphinx based docs can include non-api
documentation. It is a documentation tool which has the ability to bring in
outside auto generated documentation. It is not an dressed up api doc
generator.

The Plone sphinx based docs can and probably will become more like the bfg
narrative docs

http://static.repoze.org/bfgdocs/#narrative-documentation

than the existing api.plone.docs.

Developers using Plone *need* narrative documentation.
Plone.org doesn't do that at least in its current unstructured form. Sphinx
can and will and in the end it's a better place for it since the collective
is more open, more transparent and more developer friendly than Plone.org
docs, IMO.



-------------------------------------------------------------------------
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 12:36 AM, Dylan Jay wrote:

>> As for using sphinx to document our API...well it's still only as  
>> good
>> as what developers put in the API. If people aren't documenting their
>> code then it won't be in there. Sphinx makes it look a lot nicer than
>> the old api.plone.org, that's for sure. But until people change their
>> habits and make documentation a priority, it's not going to help too
>> much.
>
> Just to be 100% crystal clear: sphinx based docs can include non-api
> documentation. It is a documentation tool which has the ability to  
> bring in
> outside auto generated documentation. It is not an dressed up api doc
> generator.
>
> The Plone sphinx based docs can and probably will become more like  
> the bfg
> narrative docs
>
> http://static.repoze.org/bfgdocs/#narrative-documentation
>
> than the existing api.plone.docs.

The repoze docs are very nice.  Of course they have a smaller (i.e.  
"less ambitious and less featureful") codebase to document.  A more  
ambitious example of sphinx based docs would be http://docs.python.org/dev/

I'm intrigued but I'm not clear what sphinx buys you other than  
perhaps an easy way to incorporate API docs into a freeform narrative  
document,



> Developers using Plone *need* narrative documentation.
> Plone.org doesn't do that at least in its current unstructured form.  
> Sphinx
> can and will and in the end it's a better place for it since the  
> collective
> is more open, more transparent and more developer friendly than  
> Plone.org
> docs, IMO.


More open, transparent, developer-friendly?  Perhaps.  Sounds good,  
but what precisely do you mean by these terms?

More open in the sense that anyone can contribute without editorial  
control?  I'm not sure I care for that.  Who will manage this?  Even  
in the collective, someone assumes the responsibility to manage  
releases which can often mean reviewing, revising, and discarding  
contributions.  Other than the lack of a built-in workflow, how would  
this svn-mediated editorial process be any different than editorial  
oversight on Plone.org?

More transparent in that all contributions are publicly logged and  
tracked?  I guess if we really feel this is necessary, it should be  
easy enough to make the edit history of Plone.org docs publicly  
accessible.  But why?

More developer-friendly due to reStructuredText and subversion?  Are  
developers more comfortable with editing reStructuredText source docs  
in subversion repositories than using Kupu to edit documents in a  
Plone CMS?  Shrug.

More developer-friendly because the docs are edited alongside the  
developer's product code?  Okay.  But then, some of the best  
documentation comes from users and integrators, not from developers.  
How would non-developers get to contribute?

Again, I'm intrigued.  Definitely sounds like it could be an  
improvement over the plain vanilla api.plone.org.  Might also be real  
nice if sphinx based docs could be incorporated into the add-on  
product documentation available at http://plone.org/products/.  This  
certainly seems like it has the potential to encourage developers to  
document as they develop, but it isn't clear how any of this is  
*better* than the current relatively "open" and "user-friendly"  
process to contribute non-api documentation on Plone.org.  Different,  
yes.  Potentially useful, yes.  Better? Seems a little like asserting  
that *book* documentation is better than *online* documentation.  They  
can both be good but they tend to fill different niches.  Which is  
better?  Shrug.

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