[Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Alex Clark]

Hi,

Here is a re-print of the last section of my last email to the "longest doc team thread of all time".

That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
we can create multiple PHCs inside a top level /documentation folder, to try to make
everyone happy.

(I would also like to trick Martin into reading this thread again ;-))

This has several distinct advantages as far as I can tell:

Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).

By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).

Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).

Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.

Anyway, here it is:

---

Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).

I am starting to feel like that satisfies the most number of folks and has
the least number of drawbacks:

- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0

If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.

Thoughts?

The one drawback I can think of is that if I search for "apache" i might get
an "old" copy of the content. But if that content is in:

http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/

or

http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/

I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).

And if a URL like:

http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/

was published and 3.3.5 did not match PHC's idea of the current release, the
template could insert an "info box" that said:

================================================================================
|Info (i) |
|Are you sure you were not looking for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-apache/ ? |
================================================================================

Any takers?

---

One last thing, if it is starting to feel like X.X.X is too may revisions of docs
(which it was to me just now) consider this:

http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/

This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)

Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.

Alex

[Israel Saeta Pérez]

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the "longest doc team thread of all time".

I'd bet longest doc team thread of all time was the one started by Mikko
some months ago.

Post by Alex Clark
That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
we can create multiple PHCs inside a top level /documentation folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).

Plone Documentation is not a stalled nor a struggling project. We're
making constant progress in several areas. I can say that documenting
Plone 4 has been an important success, with only 2 PLIPs left (I'll have
to lean on some people) and an User Manual with new Sunburst screenshots
(something that requires a lot of mundane work). We're also preparing
videos for the User Manual (which had not been updated since Plone 2)
and an Installation Guide.

Post by Alex Clark
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).

Most of our documentation will apply to both Plone 3 and 4 (and even
2.5). The parts only applying to Plone 4 have been marked appropriately,
either as a whole like the Plone 4 User Manual, or specifically
mentioning so in the associated paragraph. We are looking for special
styles to tag version-specific stuff so it can be easily recognizable.

Post by Alex Clark
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).

I'm very concerned with the split you're proposing. For the people
writing documentation, this could mean duplicating (or more) the amount
of work.

We care about where the documentation is placed because we want the best
for the project, and reduce the amount of unnecessary work. We're not
just machines to throw a piece of code to document at. If we feel this
is growing the wrong way and we can't get involved into the decisions
because they correspond to the "website team", we'll become demoralized
and just quit.

Post by Alex Clark
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?

This wouldn't work, since current documentation applies to both Plone 3
and Plone 4. As you can see, the process is not stalled. :)

If we copied and moved the documentation as you suggest, then if I
wanted to document something present in both Plone 4.0 and 3.3.6, I
would have to update the docs in both areas, which would mean double
work. This is one of the strongest points I have against your proposal,
and what makes me dismiss it now.

If there are problems to identify which Plone version a certain document
applies to, what we have to do is to improve how do we present this
information visually, not to duplicate content and work.

Post by Alex Clark
[...]
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)

It would be more effective to correct the giant mistake right away in a
single doc, so the correction would be available immediately, instead of
having to wait for the next release.


I don't want you to see this as "stop energy". This would be like if you
blamed the FWT for rejecting a PLIP which is not well-thought or too
risky. I know you want the best for the documentation, but in this case
the best, as Anne says, is to get the actual work done instead of
performing unnecessary big changes.

You can take a look at https://dev.plone.org/plone/report/8 and pick any
task, or garden them.

-- israel

[Anne Bowtell]

Post by Israel Saeta Pérez
Plone Documentation is not a stalled nor a struggling project. We're
making constant progress in several areas. I can say that documenting
Plone 4 has been an important success, with only 2 PLIPs left (I'll have
to lean on some people) and an User Manual with new Sunburst screenshots
(something that requires a lot of mundane work). We're also preparing
videos for the User Manual (which had not been updated since Plone 2)
and an Installation Guide.

Indeed, this is very much due to Israel's hard work. He has taken
responsibility for carrying the documentation work forward by committing
time to managing the process and actually doing the basic work. Given
his assumption of responsibility I also think that his views should be
given particular weight and respect.

Post by Israel Saeta Pérez
Most of our documentation will apply to both Plone 3 and 4 (and even
2.5). The parts only applying to Plone 4 have been marked appropriately,
either as a whole like the Plone 4 User Manual, or specifically
mentioning so in the associated paragraph. We are looking for special
styles to tag version-specific stuff so it can be easily recognizable.

This is a simple, pragmatic solution which enables us to get on with the
core job of pulling the documentation into shape, following the plans
which the documentation team has put together over the last 18 months.

Post by Israel Saeta Pérez

Post by Alex Clark
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?

This wouldn't work, since current documentation applies to both Plone 3
and Plone 4. As you can see, the process is not stalled. :)
If we copied and moved the documentation as you suggest, then if I
wanted to document something present in both Plone 4.0 and 3.3.6, I
would have to update the docs in both areas, which would mean double
work. This is one of the strongest points I have against your proposal,
and what makes me dismiss it now.
If there are problems to identify which Plone version a certain document
applies to, what we have to do is to improve how do we present this
information visually, not to duplicate content and work.

I agree with Israel, from where I stand, this is an unworkable
suggestion which makes me deeply unhappy. I think its unlikely I'd be
able to participate further in documentation on plone.org in that scenario.

Post by Israel Saeta Pérez
You can take a look at https://dev.plone.org/plone/report/8 and pick any
task, or garden them.

I intend to add to these over the weekend, if anyone would like to join me.

Best wishes

Anne

[Alex Clark]

Post by Anne Bowtell
Indeed, this is very much due to Israel's hard work. He has taken
responsibility for carrying the documentation work forward by committing
time to managing the process and actually doing the basic work. Given
his assumption of responsibility I also think that his views should be
given particular weight and respect.

Of course! I have nothing but respect for both you, was just trying to "help".

Post by Anne Bowtell
I agree with Israel, from where I stand, this is an unworkable
suggestion which makes me deeply unhappy. I think its unlikely I'd be
able to participate further in documentation on plone.org in that scenario.

Well that's a shame. But of course, I do not want to make anyone unhappy. So
let's leave it alone for a while.

Post by Anne Bowtell

Post by Israel Saeta Pérez
You can take a look at https://dev.plone.org/plone/report/8 and pick any
task, or garden them.

I intend to add to these over the weekend, if anyone would like to join me.

I intend to help, but not until I've fully recovered from
https://www.packtpub.com/plone-3-3-site-administration/book

;-)

Post by Anne Bowtell
Best wishes
Anne
--------------060707030303000401000102
Content-Type: text/x-vcard; charset=utf-8;
name="anne_bowtell.vcf"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="anne_bowtell.vcf"
begin:vcard
fn:Anne Bowtell
n:Bowtell;Anne
tel;work:[phone]
x-mozilla-html:FALSE
version:2.1
end:vcard
--------------060707030303000401000102
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
------------------------------------------------------------------------------
--------------060707030303000401000102
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs
--------------060707030303000401000102--

[Alex Clark]

Hi,

Post by Israel Saeta Pérez
Plone Documentation is not a stalled nor a struggling project.

In your opinion. mine, it is.

Post by Israel Saeta Pérez
We're
making constant progress in several areas. I can say that documenting
Plone 4 has been an important success, with only 2 PLIPs left (I'll have
to lean on some people) and an User Manual with new Sunburst screenshots
(something that requires a lot of mundane work). We're also preparing
videos for the User Manual (which had not been updated since Plone 2)
and an Installation Guide.

That's great!

Post by Israel Saeta Pérez
Most of our documentation will apply to both Plone 3 and 4 (and even
2.5). The parts only applying to Plone 4 have been marked appropriately,
either as a whole like the Plone 4 User Manual, or specifically
mentioning so in the associated paragraph. We are looking for special
styles to tag version-specific stuff so it can be easily recognizable.

Sounds good.

Post by Israel Saeta Pérez
I'm very concerned with the split you're proposing. For the people
writing documentation, this could mean duplicating (or more) the amount
of work.
We care about where the documentation is placed because we want the best
for the project, and reduce the amount of unnecessary work. We're not
just machines to throw a piece of code to document at. If we feel this
is growing the wrong way and we can't get involved into the decisions
because they correspond to the "website team", we'll become demoralized
and just quit.

OK

Post by Israel Saeta Pérez
This wouldn't work, since current documentation applies to both Plone 3
and Plone 4. As you can see, the process is not stalled. :)

I don't see that. I don't see anyone (at least on this list) understanding
the process but you and Anne. I could be wrong, of course.

Post by Israel Saeta Pérez
If we copied and moved the documentation as you suggest, then if I
wanted to document something present in both Plone 4.0 and 3.3.6, I
would have to update the docs in both areas, which would mean double
work. This is one of the strongest points I have against your proposal,
and what makes me dismiss it now.

Welcome to software and documentation.

Post by Israel Saeta Pérez
If there are problems to identify which Plone version a certain document
applies to, what we have to do is to improve how do we present this
information visually, not to duplicate content and work.

If you say so, I disagree, obviously.

Post by Israel Saeta Pérez
It would be more effective to correct the giant mistake right away in a
single doc, so the correction would be available immediately, instead of
having to wait for the next release.

Again, "effective" in your opinion.

Post by Israel Saeta Pérez
I don't want you to see this as "stop energy". This would be like if you
blamed the FWT for rejecting a PLIP which is not well-thought or too
risky. I know you want the best for the documentation, but in this case
the best, as Anne says, is to get the actual work done instead of
performing unnecessary big changes.

It would be hard for me to not see this as stop energy, TBH. Maybe others
have a different perspective…

Post by Israel Saeta Pérez
You can take a look at https://dev.plone.org/plone/report/8 and pick any
task, or garden them.

Right.

Post by Israel Saeta Pérez
-- israel
------------------------------------------------------------------------------

[Alex Clark]

Post by Alex Clark
Hi,

Post by Israel Saeta Pérez
Plone Documentation is not a stalled nor a struggling project.

In your opinion. mine, it is.

OOPS, A small bird in my ear has pointed out that this comment might be considered offensive
to Israel (who must be given an enormous amount of credit for leading the doc team),
which was not my intention.

Israel, I apologize! :-)

I'm only voicing my own personal frustration with the current situation, and
trying to help. Anyway, carry on folks, and keep up the great work! :-)

Post by Alex Clark

Post by Israel Saeta Pérez
We're
making constant progress in several areas. I can say that documenting
Plone 4 has been an important success, with only 2 PLIPs left (I'll have
to lean on some people) and an User Manual with new Sunburst screenshots
(something that requires a lot of mundane work). We're also preparing
videos for the User Manual (which had not been updated since Plone 2)
and an Installation Guide.

That's great!

Post by Israel Saeta Pérez
Most of our documentation will apply to both Plone 3 and 4 (and even
2.5). The parts only applying to Plone 4 have been marked appropriately,
either as a whole like the Plone 4 User Manual, or specifically
mentioning so in the associated paragraph. We are looking for special
styles to tag version-specific stuff so it can be easily recognizable.

Sounds good.

Post by Israel Saeta Pérez
I'm very concerned with the split you're proposing. For the people
writing documentation, this could mean duplicating (or more) the amount
of work.
We care about where the documentation is placed because we want the best
for the project, and reduce the amount of unnecessary work. We're not
just machines to throw a piece of code to document at. If we feel this
is growing the wrong way and we can't get involved into the decisions
because they correspond to the "website team", we'll become demoralized
and just quit.

OK

Post by Israel Saeta Pérez
This wouldn't work, since current documentation applies to both Plone 3
and Plone 4. As you can see, the process is not stalled. :)

I don't see that. I don't see anyone (at least on this list) understanding
the process but you and Anne. I could be wrong, of course.

Post by Israel Saeta Pérez
If we copied and moved the documentation as you suggest, then if I
wanted to document something present in both Plone 4.0 and 3.3.6, I
would have to update the docs in both areas, which would mean double
work. This is one of the strongest points I have against your proposal,
and what makes me dismiss it now.

Welcome to software and documentation.

Post by Israel Saeta Pérez
If there are problems to identify which Plone version a certain document
applies to, what we have to do is to improve how do we present this
information visually, not to duplicate content and work.

If you say so, I disagree, obviously.

Post by Israel Saeta Pérez
It would be more effective to correct the giant mistake right away in a
single doc, so the correction would be available immediately, instead of
having to wait for the next release.

Again, "effective" in your opinion.

Post by Israel Saeta Pérez
I don't want you to see this as "stop energy". This would be like if you
blamed the FWT for rejecting a PLIP which is not well-thought or too
risky. I know you want the best for the documentation, but in this case
the best, as Anne says, is to get the actual work done instead of
performing unnecessary big changes.

It would be hard for me to not see this as stop energy, TBH. Maybe others
have a different perspective…

Post by Israel Saeta Pérez
You can take a look at https://dev.plone.org/plone/report/8 and pick any
task, or garden them.

Right.

Post by Israel Saeta Pérez
-- israel
------------------------------------------------------------------------------

[Israel Saeta Pérez]

Post by Alex Clark

Post by Alex Clark
Hi,

Post by Israel Saeta Pérez
Plone Documentation is not a stalled nor a struggling project.

In your opinion. mine, it is.

OOPS, A small bird in my ear has pointed out that this comment might be considered offensive
to Israel (who must be given an enormous amount of credit for leading the doc team),
which was not my intention.
Israel, I apologize! :-)

It sligthly was, yes, but I accept your apologies.


-- israel

[Dylan Jay]

Hi alex,
Not sure if you are over the split between kb docs and manuals. Since
kb is edited by everyone Its going to be much harder to ensure that
versions make sense. It should be used for "edge" type docs and
evolving ones like faqs, where as the core docs will be removed from
there and consolidated into manals. So I think it only makes sense to
version manuals.
And really a LOT of the documentation is developer related so
versioning the developer manual is going to be the single biggest win.
Developers are the ones feeling the pain of not knowing if the
tecquiues they are reading are up to date or not.

Dylan Jay
Technical solution manager
PretaWeb 99552830

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the
"longest doc team thread of all time".
That thread has gotten a bit unwieldy, so I'd like to start a new
convo based on the idea that
we can create multiple PHCs inside a top level /documentation
folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5
compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/
3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/
release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?
The one drawback I can think of is that if I search for "apache" i might get
http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/
or
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
was published and 3.3.5 did not match PHC's idea of the current release, the
===
===
===
===
====================================================================
|Info
(i)
|
|Are you sure you were not looking
for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-
apache/ ? |
===
===
===
===
====================================================================
Any takers?
---
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/kb/
plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.
Alex
--
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admi
n
---
---
---
---------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Alex Clark]

Hi Dylan,

(OOPS, I answered this off-list earlier)

Post by Dylan Jay
Hi alex,
Not sure if you are over the split between kb docs and manuals.

Probably not. I get that a "knowledge base" is more volatile…

Post by Dylan Jay
Since
kb is edited by everyone Its going to be much harder to ensure that
versions make sense. It should be used for "edge" type docs and
evolving ones like faqs, where as the core docs will be removed from
there and consolidated into manals. So I think it only makes sense to
version manuals.

Right, I get that. My only counter-point is that from the outside looking
in, I don't care :-). Versioning *everything* is a brute force way
to achieve a URL like /documentation/4.0.x/.

Perhaps I'd adjust the strategy a bit to allow the "released" KB be
edited… or I'd pull the KB completely out of the PHC and version
everything else (perhaps this is close to what you suggest).

Post by Dylan Jay
And really a LOT of the documentation is developer related so
versioning the developer manual is going to be the single biggest win.
Developers are the ones feeling the pain of not knowing if the
tecquiues they are reading are up to date or not.

Right. I take this to mean that you and I agree on versioning, but
what gets versioned underneath /documentation is debatable.

Post by Dylan Jay
Dylan Jay
Technical solution manager
PretaWeb 99552830

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the
"longest doc team thread of all time".
That thread has gotten a bit unwieldy, so I'd like to start a new
convo based on the idea that
we can create multiple PHCs inside a top level /documentation
folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5
compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/
3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/
release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?
The one drawback I can think of is that if I search for "apache" i might get
http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/
or
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
was published and 3.3.5 did not match PHC's idea of the current release, the
===
===
===
===
====================================================================
|Info
(i)
|
|Are you sure you were not looking
for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-
apache/ ? |
===
===
===
===
====================================================================
Any takers?
---
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/kb/
plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.
Alex
--
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admi
n
---
---
---
---------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay]

Post by Alex Clark
Hi Dylan,
(OOPS, I answered this off-list earlier)

Post by Dylan Jay
Hi alex,
Not sure if you are over the split between kb docs and manuals.

Probably not. I get that a "knowledge base" is more volatile…

Post by Dylan Jay
Since
kb is edited by everyone Its going to be much harder to ensure that
versions make sense. It should be used for "edge" type docs and
evolving ones like faqs, where as the core docs will be removed from
there and consolidated into manals. So I think it only makes sense to
version manuals.

Right, I get that. My only counter-point is that from the outside looking
in, I don't care :-). Versioning *everything* is a brute force way
to achieve a URL like /documentation/4.0.x/.

I think part of the problem here is that the documentation is
currently in flux between and old and a new structure, so we can't
look at it from the outside and make judgements on how it will be once
this latest change is finished.
Once limi finishes the doc area UI there should be much more emphasis
on official manuals and the kb area should appear much more like a
staging area for new forms or ideas in documetnation, e.g. how do I
get deploy to ec2, or how do I integrate SOAP. When those things
become "core" then they get moved into the manuals section (which I
believe should be versioned).
I think Israel and Anna are sort of saying the same thing, that
version makes sense for "mature" documentation, not for all
documentation. Hense why the user manual has already been versioned.
The user manual is mature, the themeing manual isn't. The developer
manual should be our primary focus to make that mature ASAP. The KB
will never be mature, it's not meant to be.
Also don't forget that version tags will still exist in the KB. It
should be clearer than it is now. Maybe for the KB, Israel's traversal
trick is a good idea.
documentation/kb/3.3/myhowto will look up and see if the documentation/
kb/myhowto has the 3.3 version tag and then display it accordingly.

But I don't think that's how manuals should be versioned. The plone
4.0 developer manual should be carefully edited to ensure it's only
relevant to 4 and removes old stuff only relevant to 3.3.

my 2c anyway. and of course I'm not doc team either I totally respect
the hard work being put in by the doc team and I think that we should
be considering workload as well as making clearer for readers. I think
there is a compromise possible here.

Post by Alex Clark
Perhaps I'd adjust the strategy a bit to allow the "released" KB be
edited… or I'd pull the KB completely out of the PHC and version
everything else (perhaps this is close to what you suggest).

My understanding is that KB == PHC and manuals doesn't really have to
be PHC.

Post by Alex Clark

Post by Dylan Jay
And really a LOT of the documentation is developer related so
versioning the developer manual is going to be the single biggest win.
Developers are the ones feeling the pain of not knowing if the
tecquiues they are reading are up to date or not.

Right. I take this to mean that you and I agree on versioning, but
what gets versioned underneath /documentation is debatable.

yep.

Post by Alex Clark

Post by Dylan Jay
Dylan Jay
Technical solution manager
PretaWeb 99552830

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the
"longest doc team thread of all time".
That thread has gotten a bit unwieldy, so I'd like to start a new
convo based on the idea that
we can create multiple PHCs inside a top level /documentation folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread
again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5
compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/
3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/
release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?
The one drawback I can think of is that if I search for "apache" i might get
http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/
or
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
was published and 3.3.5 did not match PHC's idea of the current release, the
===
===
===
===
====================================================================
|Info
(i)
|
|Are you sure you were not looking
for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-
apache/ ? |
===
===
===
===
====================================================================
Any takers?
---
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/
kb/
plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.
Alex
--
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admi
n
---
---
---
---------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

--
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin
------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Larry Pitcher]

Hi,

I'm not on the doc team, but Alex's idea makes sense to me. It follows
the same pattern as the Apache docs, so it's not like it's never been
tried before :-)

my $0.02

Larry Pitcher

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the "longest doc team thread of all time".
That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
we can create multiple PHCs inside a top level /documentation folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?
The one drawback I can think of is that if I search for "apache" i might get
http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/
or
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
was published and 3.3.5 did not match PHC's idea of the current release, the
================================================================================
|Info (i) |
|Are you sure you were not looking for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-apache/ ? |
================================================================================
Any takers?
---
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.
Alex

[Alex Clark]

Hi Larry,

Post by Larry Pitcher
Hi,
I'm not on the doc team, but Alex's idea makes sense to me.

I think at least a half a dozen folks on this list have expressed interest
in some sort of versioning in response to my two proposals. That's why I am
declaring the doc teams failure to address it as "stop energy"
and I am moving on ;-)

I don't blame them, I mean I get the reason (sort of). But I think *something*
could be done to address the concern rather than complete inflexibily,
and unwillingness to do anything but declare that they will do nothing.

Correct me if I am wrong guys, but the only counter-suggestion I have received
from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start
closing doc tickets. :-p

And, I (seriously) plan to start doing that, ASAP. But I was hoping to address
some macro-issues first…

(Well, there was also the "traversal hack" suggestion, to be fair. Which I guess
I am not opposed to, but I don't see it working in a way that would satisfy
"versioning". I could be wrong.)

Post by Larry Pitcher
It follows
the same pattern as the Apache docs, so it's not like it's never been
tried before :-)

True. It makes sense for a variety of reasons. :-)

Post by Larry Pitcher
my $0.02

I appreciate your feedback! And all of this is just my 0.02 cents… I'm not
really on the doc team either (although I like to dabble).

Post by Larry Pitcher
Larry Pitcher

Post by Alex Clark
Hi,
Here is a re-print of the last section of my last email to the "longest doc team thread of all time".
That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
we can create multiple PHCs inside a top level /documentation folder, to try to make
everyone happy.
(I would also like to trick Martin into reading this thread again ;-))
Gives immediacy
===============
It creates a sense of immediacy for what (at least I, maybe others) perceive as
a "stalled" project (or at least struggling project).
By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
Ends confusion
==============
It completely eliminates the "what does this apply to?" problem. If something
Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
because we know the same item exists in the Plone 3 folder, where it should be
(or you clean it up for Plone 4, and leave the Plone 3 doc alone).
Lets things die
===============
When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
by the community) we can privatize the folder. We have no way to kill things
other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.
---
Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in
various branches and at least one tag).
I am starting to feel like that satisfies the most number of folks and has
- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0
If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.
Thoughts?
The one drawback I can think of is that if I search for "apache" i might get
http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/
or
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
I imagine folks could just "figure it out" ;-) I also imagine that it would be
easy (i.e. even something I could program ;-)) to add something to PHC that would
allow it to know what the current release is (similar to PSC).
http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/
was published and 3.3.5 did not match PHC's idea of the current release, the
================================================================================
|Info (i) |
|Are you sure you were not looking for: |
|http://plone.org/documentation/release/4.0/kb/plone-with-apache/ ? |
================================================================================
Any takers?
---
One last thing, if it is starting to feel like X.X.X is too may revisions of docs
http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
Another *last* thing. I'd be willing to stage this somewhere if people would be willing
to take a swipe at it. We could even invite the entire community to participate, given
that the results could be thrown away if the experiment did not go well.
Alex

[Israel Saeta Pérez]

I didn't plan to continue replying to what can become the longest thread
in the plone-docs list, but

Post by Alex Clark
Hi Larry,

Post by Larry Pitcher
Hi,
I'm not on the doc team, but Alex's idea makes sense to me.

Time ago we decided to make a distinction between "doc team" and "doc
team editors".

The doc team editors were assigned to certain areas (theming,
development, basic use, etc.) and had the responsibility to garden them
and review new submission. This responsibility also involved a power,
which was the power of taking part on the decisions when something
important or controversial had to be decided upon, like happened with
the manuals/KB split. It was a sort of collective documentation release
manager.

As doc team, I consider that everyone interested in documentation is
part of the doc team. Obviously it's not just Anne, Steve and me who
write documentation, but many other people, like Mikko or any of the
developers who contributed to document their PLIPs.

Post by Alex Clark
I think at least a half a dozen folks on this list have expressed interest
in some sort of versioning in response to my two proposals. That's why I am
declaring the doc teams failure to address it as "stop energy"
and I am moving on ;-)

I don't want anybody to see my opinions as "enlightened absolutism".
While I've been proposed once or twice to become a kind of
"documentation team leader", I've never been officially appointed (like
Eric has been as Release Manager). So I can only give my point of view
as someone who has been already working with Plone documentation for a
while, specially involved in updating it to include changes related to
newer Plone versions, and therefore think my opinion is something valuable.

However, since I'm in no official position to make "political
decisions", I accept moving in other directions if a majority of people
agrees.

Honestly, it's really sad to see how the few people really working on
documentation have historically been target of quite hard critics
everytime someone hesitated upon a risky movement. These people
hard-worked, and yet found that others feel the documentation is stalled
and have great plans to drastically and suddenly improve it. It's not a
secret that most of them quit, demoralized from the lack of appreciation
for their work.

When one gives his opinion to try to go the right way and is answered
with an "In your opinion. mine, it is." or "this is stop energy", what
one thinks is just to quit and let others free their energy and do
things the Right Way.

Post by Alex Clark
I don't blame them, I mean I get the reason (sort of). But I think *something*
could be done to address the concern rather than complete inflexibily,
and unwillingness to do anything but declare that they will do nothing.

Untrue, read below.

Post by Alex Clark
Correct me if I am wrong guys, but the only counter-suggestion I have received
from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start
closing doc tickets. :-p

There are other ways to solve the problem of showing what version of
Plone a certain approach corresponds to, like using the current PHC
metadata (and trying to highlight this info in the presentation) and
writing it in the appropriate paragraphs, as we've been doing. This has
already been mentioned before.

I suggested to work on current, well identified stuff captured in the
form of tickets since I know that everyone loves taking part in big
changes that are going to drastically improve the current situation, but
very few people takes care of real documentation writing and other more
mundane stuff.

I really don't want to spend more time in this politics thing. I don't
want to fight against half a dozen of people and keep saying the same
arguments over and over again. I want to spend my time in preparing easy
tasks for the people in the upcoming Sorrento Sprint to contribute.

-- israel

[Alex Clark]

Post by Israel Saeta Pérez
I didn't plan to continue replying to what can become the longest thread
in the plone-docs list, but

Heh

Post by Israel Saeta Pérez

Post by Alex Clark
Hi Larry,

Post by Larry Pitcher
Hi,
I'm not on the doc team, but Alex's idea makes sense to me.

Time ago we decided to make a distinction between "doc team" and "doc
team editors".
The doc team editors were assigned to certain areas (theming,
development, basic use, etc.) and had the responsibility to garden them
and review new submission. This responsibility also involved a power,
which was the power of taking part on the decisions when something
important or controversial had to be decided upon, like happened with
the manuals/KB split. It was a sort of collective documentation release
manager.

I vaguely remember this. Maybe documenting this process, along with the FWT
process (which I believe Hanno is working on documenting) would help folks
on the outside to see in.

Post by Israel Saeta Pérez
As doc team, I consider that everyone interested in documentation is
part of the doc team. Obviously it's not just Anne, Steve and me who
write documentation, but many other people, like Mikko or any of the
developers who contributed to document their PLIPs.

Right, kind of like the "code team" is not just Eric plus the FWT.

Post by Israel Saeta Pérez

Post by Alex Clark
I think at least a half a dozen folks on this list have expressed interest
in some sort of versioning in response to my two proposals. That's why I am
declaring the doc teams failure to address it as "stop energy"
and I am moving on ;-)

I don't want anybody to see my opinions as "enlightened absolutism".
While I've been proposed once or twice to become a kind of
"documentation team leader", I've never been officially appointed (like
Eric has been as Release Manager). So I can only give my point of view
as someone who has been already working with Plone documentation for a
while, specially involved in updating it to include changes related to
newer Plone versions, and therefore think my opinion is something valuable.
However, since I'm in no official position to make "political
decisions", I accept moving in other directions if a majority of people
agrees.
Honestly, it's really sad to see how the few people really working on
documentation have historically been target of quite hard critics
everytime someone hesitated upon a risky movement. These people
hard-worked, and yet found that others feel the documentation is stalled
and have great plans to drastically and suddenly improve it. It's not a
secret that most of them quit, demoralized from the lack of appreciation
for their work.

No doubt, and one of my goals in stirring all this up was to try and find
a way to bring some of that "reward" from the outside (i.e. appreciation).
I hope I have expressed enough my own appreciation.

Post by Israel Saeta Pérez
When one gives his opinion to try to go the right way and is answered
with an "In your opinion. mine, it is." or "this is stop energy", what
one thinks is just to quit and let others free their energy and do
things the Right Way.

Well, the goal is to work together, and incorporate everyone's ideas, IMO.
But I agree the doc team has been unfortunately subjected to way too
much "hey what's going on in here, poke, poke".

Post by Israel Saeta Pérez

Post by Alex Clark
I don't blame them, I mean I get the reason (sort of). But I think *something*
could be done to address the concern rather than complete inflexibily,
and unwillingness to do anything but declare that they will do nothing.

Untrue, read below.

OK

Post by Israel Saeta Pérez

Post by Alex Clark
Correct me if I am wrong guys, but the only counter-suggestion I have received
from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start
closing doc tickets. :-p

There are other ways to solve the problem of showing what version of
Plone a certain approach corresponds to, like using the current PHC
metadata (and trying to highlight this info in the presentation) and
writing it in the appropriate paragraphs, as we've been doing. This has
already been mentioned before.
I suggested to work on current, well identified stuff captured in the
form of tickets since I know that everyone loves taking part in big
changes that are going to drastically improve the current situation, but
very few people takes care of real documentation writing and other more
mundane stuff.

Right, and these are good suggestions… I think we will just have to
agree to disagree on whether or not they address my specific concern.

Post by Israel Saeta Pérez
I really don't want to spend more time in this politics thing. I don't
want to fight against half a dozen of people and keep saying the same
arguments over and over again. I want to spend my time in preparing easy
tasks for the people in the upcoming Sorrento Sprint to contribute.

Indeed, sorry for the noise.

My one final suggestion is that it usually never hurts to encourage folks to
run with a particular "crazy" idea, and let it run its course on its
own, without telling them your opinion of it (and therefore discouraging
innovation).

IOW, I setup collective-docs.plone.org, which I suspect Mikko and Dylan
are not the biggest fans of, because it kind of short circuits their
long term goals (AFAICT). ;-) But it is relatively harmless, and if
they asked me to turn it off, I would.

In the same way, like I said, I could create crazy-phc.plone.org as
an experiment, and reorganize all the content i wanted to. It may
be well liked, it or it may go nowhere. But the "spotlight energy"
(i.e. attention from the outside directed in) is thus re-directed
away from doc team list, where it can be destructive (as I
am learning).

The equivalent to this in software land is branches. And if you look
through the collective and plone repos you will find the rotting
corpses of (literally!) hundreds of bad or unfinished ideas. :-)

Ciao

Post by Israel Saeta Pérez
-- israel
------------------------------------------------------------------------------

[Raphael Ritz]

Post by Larry Pitcher
Hi,
I'm not on the doc team, but Alex's idea makes sense to me. It follows
the same pattern as the Apache docs, so it's not like it's never been
tried before :-)

Hi,

I didn't follow the full discussion but from what
I understood so far people are concerned about
providing URLs like

docs/manual/4.0/...
docs/manual/3.3.5/...

would require duplicating contents thereby creating
a maintenance nightmare.

Has it been considered to use alternative means
to achieve the same thing like (i) topics - customized
if needed or (ii) clever traversers based on, e.g.,
how doc items are tagged? (Quills provides an example
for the latter to make blog posts available under
"date-like" URLs even though they are all in the same
folder.)

Just a thought,

Raphael

Post by Larry Pitcher
my $0.02
Larry Pitcher