A proposal for a way forward and a call for volunteers

[Martin Aspeli-2]

Hi guys,

First of all, I'd like to thank you for all your hard work over the past
few weeks. I feel like we have some momentum and energy again, and it's
making not only me, but people like Limi and Wiggy extremely happy as well.

I think it's time to put some of our plans into action. Before we do
that, though, I'd like to summarise the challenges we've discussed to
date, and then try to identify some specific tasks we need volunteers for.

Consider this a strongly worded proposal. I hope there is agreement
about most of these points. I would like us to vote on whether this is
the right way to go, broadly. Some of the finer details of actions can
be worked out later. I'd also like to have the voting closed by Sunday
Feb 18th. There are not so many of us anyway. :)

The challenges
==============

Plone documentation faces a number of challenges currently:

  - Some areas of Plone are still under-documented, either because they
are poorly understood, or because they are boring to document.

  - Rapid change to Plone means it's hard to keep things up to date.

  - The volume of documentation has become difficult to manage. There
are duplications and overlaps.

  - Our team is too small for the task of managing all the documentation
for all of Plone all the time.

The reality
===========

To inject a dose of reality, there are a number of points we need to
bear in mind:

  - Good documentation-writers are hard to come by. Not everyone is
created equal when it comes to writing good documentation for different
audiences. This means we will always have varying quality of writing in
our documentation.

  - We can't afford to turn people away. Sometimes, an OK how-to can be
just the thing someone needs to complete their project at 4am in the
morning. We do pretty well here, in that the barrier to contribution is
fairly low, the review cycle is fairly light, and we actively encourage
people to write short how-tos when they solve a particular problem.

  - We also can't afford for people to be completely overwhelmed by the
documentation or, worse, be misled by incorrect or out-of-date pieces.

  - Some of the areas where we may not be ideally suited to succeed is
handled by published books. That's perfectly fine. Writing something as
consistent and complete as a book takes more effort from more people
than what we should reasonably expect volunteers to take on. At the same
time, not everyone learns well from books, and books are always out of date.

  - The people who would reasonably invest more than a casual amount of
time on documentation do not collectively have enough knowledge of some
aspects of Plone to be able to write exhaustively about all the topics.

What we are are not doing
=========================

It's very easy to begin thinking from a blank sheet of paper and come up
with a utopian documentation story. In the perfect world, we'd have
infinite time, every author would be eloquent and write perfectly, there
would be no overlap, and it would all be organised splendidly. Alas, we
will never get there. What we need to do is to make the best of what we
have to work with, and find innovative solutions that bear some of the
realities above in mind.

The most important reality is the lack of time. With that in mind, here
are a few things I specifically do *not* want to focus on:

  - We should not go down any route that involve re-writing all the
documentation.

  - We should not go down any route that requires in-depth editorial
review of every piece of documentation. We did that once, with a larger
team than this one and a quarter as many pieces of documentation, and it
took months just to get back to something which was as good as the what
we had before.

  - We should not require every documentation author to re-do and
re-submit their work. We may choose to edit or retract some bad
documentation, and offer authors the chance to try again, but it is
unrealistic to expect people to have time to re-do documentation they
feel they've already given the community. This is doubly dangerous,
because it risks alienating the very people who's support we need.

  - We should not segregate documentation so clearly that a large number
of people who've contributed documentation feels their efforts are
marginalised and thus not worth the effort.

  - We will not invent radically new technology. The PHC has taken years
to be complete, again mostly for lack of time, but it works reasonably
well. We can, and should, make incremental improvements to it, e.g. by
adding ratings. We will not introduce anything that will require complex
migration from the existing data structures.

We can of course not stop anyone from going down any of these routes,
but these sentiments are based on our previous experience at a similar
pinch-point around the time of Plone 2.1. They are endorsed by Limi,
Wiggy and various past and present members of the team.

Perhaps we can engage with some of these at a later date, but for now,
we have more urgent needs that require more immediate attention, and
some grand adventure of documentation will get in our way.

What we should do
=================

Here is a set of action points that have come out of our previous
discussions, as well as brainstorms with Alex and others.

  - Produce a documentation guide -

:: Requires: 1 volunteer to pull it together and own it

This should be a short Tutorial, and incorporate style guidelines,
structural guidelines for the main types of documentation (How-to,
tutorial, manual), and general tips on writing good documentation. A lot
of this work has been started and discussed in the past few weeks.

  - Produce templates for each type of documentation -

:: Requires: 1 volunteer to extend PHC to support documentation
templates, 1 volunteer to collect and manage the templates themselves

When a new how-to, tutorial or manual is created, it should be
pre-populated with suggested headings (for how-tos, in particular) and
sections (for tutorials and manuals), such as "Introduction", "Who is
this for?" and "Conclusion". People should be free to change this if
they feel it's appropriate. Imposing this structure on all existing
documentation i explicitly *out* of scope at this time. The purpose is
to give people a starting point, not force them into an arbitrarily
decided structure. The sections are not metadata.

  - Produce better metadata, including ratings, for documentation -

:: Requires: 1 volunteer to extend PHC to support additional metadata,
ratings

In the first instance, documentation pieces should be ratable. We should
make views that make use of ratings to highlight popular documentation.
Ratings can be as simple as "was this useful yes/no", possibly with a
third option for "is this obsolete or incorrect?". We should extend the
existing PHC stats tools to make it easier to search for "bad"
documentation that is flagged up.

We may also decide to capture additional metadata provided (a) it has a
clear purpose; (b) existing documentation does not need to be reviewed
one-by-one to make the metadata useful; and (c) it does not place
unnecessary burdens on documentation authors.

  - Produce and document ongoing documentation processes -

:: Requires: 1 volunteer to own the process documents and co-ordinate others

Currently, we work in a very ad-hoc manner. This means that things end
up staying in the plone.org review queue for a long time, for example.
It also means that we don't have a good plan when a new version of Plone
is released, we don't necessarily anticipate changes, we don't know when
and how to take things out of the documentation issue tracker, and so on.

The main "ongoing" tasks of the docs team should be documented in a
single, concise document. These practices should be lightweight and
recognise that people have limited time. They should also be followed,
and the owner of the processes should have a license to cajole people
into helping out. This also helps us answer questions like: "Hi, I'm new
here, how can I help out with documentation?" in terms of specific
actions that volunteers can take, without needing to spend a lot of time
working out how we work (if at all).

  - Produce "trails" of documentation -

:: Requires: 1 volunteer to document and promote the "trails" mechanism,
1 volunteer to choose and structure a pilot "trail", and possibly others
to contribute to the trail.

This is by far the best idea we've had, and the most concrete task. To
summarise, instead of aiming for perfection across all documentation, we
should pick up a few key topics that we reckon most members of a
particular audience would need to know. Examples may be "Connecting to
LDAP and other user sources" or "Developing new content types". This
"front-line" documentation should be thought through in more depth than
the rest of the how-tos and short tutorials.

The idea is that people have a small number of places to start from, and
can then search for more specific documentation (over which we exercise
less tight control) once they have solid fundamentals. This makes a
manageable task out of an enormous one. It is not quite as good as
starting from scratch and producing a "Plone book", but it can be more
than good enough for audiences who just want some authoritative
information, and are willing to connect some of the dots themselves.

I propose that we start with a single trail as a pilot. Whoever
volunteers for this gets to pick. A trail should be a Reference Manual
(we'll use the sections and audiences to ensure they end up on top,
possibly also a Smart Folder or template to show them more prominently).

The first step in defining a new trail is to work out the best learning
path for the intended audience and assess this against existing
documentation. From this, a workable structure of sections and
placeholder pages should be created. Some kind of gap analysis needs to
be completed to find out how the documentation we've got already matches
what we want. Then, one of four things may happen:

(1) We link to existing how-tos and tutorials from a particular page in
the trail. There will probably be a short intro with context to save
users from having to browse through documentation that happens not to be
relevant to them.

(2) We find existing documentation that's close, but not quite good
enough. We fix it up, possibly asking for help from the original authors
or experts in the community, and apply some pressure to make it happen
quickly.

(3) We solicit new documentation, either by writing it ourselves or
asking something else nicely. Again, we prioritise this work and try to
reward people for producing something in days and weeks rather than months.

(4) We leave that part of the trail blank. We can publish a trail that's
not yet fully complete if some nice-to-have sections are missing but
it's otherwise useful. Having clearly defined holes to fill help get
things completed.

I'll stop there. I'm explicitly leaving out specific such as "deal with
Plone 3", because ideally it should be a consequence of the processes we
come up with.

What now?
=========

First of all, please vote on this. Replying with a +1 or -1 is enough.

Secondly, if we agree, pick *one* task above that you'd like to
volunteer for. Don't pick more than one. When we overstretch ourselves,
we deliver nothing. Pick a task, and do what it takes to see it through
to completion. We will work with each volunteer to set a target date for
completion, and the wider community will be available to assist you (or
I'll come after them).

Thank you,
Martin


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Donna M Snow]

Martin (and team),

I'm most interested in the "templating" aspect of this project. I may need
some guidance as to the "right" way to do it for PHC (I haven't worked with
PHC at all..but I've done a lot of templating).

-- 1 volunteer to extend PHC to support documentation templates


Donna M. Snow, Owner
C Squared Enterprises
Illuminate your web
http://www.csquaredtech.com

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Martin Aspeli
Sent: Monday, February 12, 2007 2:31 PM
To: [hidden email]
Cc: Alexander Limi
Subject: [Plone-docs] A proposal for a way forward and a call for volunteers

Hi guys,

First of all, I'd like to thank you for all your hard work over the past
few weeks. I feel like we have some momentum and energy again, and it's
making not only me, but people like Limi and Wiggy extremely happy as well.

I think it's time to put some of our plans into action. Before we do
that, though, I'd like to summarise the challenges we've discussed to
date, and then try to identify some specific tasks we need volunteers for.

Consider this a strongly worded proposal. I hope there is agreement
about most of these points. I would like us to vote on whether this is
the right way to go, broadly. Some of the finer details of actions can
be worked out later. I'd also like to have the voting closed by Sunday
Feb 18th. There are not so many of us anyway. :)

The challenges
==============

Plone documentation faces a number of challenges currently:

  - Some areas of Plone are still under-documented, either because they
are poorly understood, or because they are boring to document.

  - Rapid change to Plone means it's hard to keep things up to date.

  - The volume of documentation has become difficult to manage. There
are duplications and overlaps.

  - Our team is too small for the task of managing all the documentation
for all of Plone all the time.

The reality
===========

To inject a dose of reality, there are a number of points we need to
bear in mind:

  - Good documentation-writers are hard to come by. Not everyone is
created equal when it comes to writing good documentation for different
audiences. This means we will always have varying quality of writing in
our documentation.

  - We can't afford to turn people away. Sometimes, an OK how-to can be
just the thing someone needs to complete their project at 4am in the
morning. We do pretty well here, in that the barrier to contribution is
fairly low, the review cycle is fairly light, and we actively encourage
people to write short how-tos when they solve a particular problem.

  - We also can't afford for people to be completely overwhelmed by the
documentation or, worse, be misled by incorrect or out-of-date pieces.

  - Some of the areas where we may not be ideally suited to succeed is
handled by published books. That's perfectly fine. Writing something as
consistent and complete as a book takes more effort from more people
than what we should reasonably expect volunteers to take on. At the same
time, not everyone learns well from books, and books are always out of date.

  - The people who would reasonably invest more than a casual amount of
time on documentation do not collectively have enough knowledge of some
aspects of Plone to be able to write exhaustively about all the topics.

What we are are not doing
=========================

It's very easy to begin thinking from a blank sheet of paper and come up
with a utopian documentation story. In the perfect world, we'd have
infinite time, every author would be eloquent and write perfectly, there
would be no overlap, and it would all be organised splendidly. Alas, we
will never get there. What we need to do is to make the best of what we
have to work with, and find innovative solutions that bear some of the
realities above in mind.

The most important reality is the lack of time. With that in mind, here
are a few things I specifically do *not* want to focus on:

  - We should not go down any route that involve re-writing all the
documentation.

  - We should not go down any route that requires in-depth editorial
review of every piece of documentation. We did that once, with a larger
team than this one and a quarter as many pieces of documentation, and it
took months just to get back to something which was as good as the what
we had before.

  - We should not require every documentation author to re-do and
re-submit their work. We may choose to edit or retract some bad
documentation, and offer authors the chance to try again, but it is
unrealistic to expect people to have time to re-do documentation they
feel they've already given the community. This is doubly dangerous,
because it risks alienating the very people who's support we need.

  - We should not segregate documentation so clearly that a large number
of people who've contributed documentation feels their efforts are
marginalised and thus not worth the effort.

  - We will not invent radically new technology. The PHC has taken years
to be complete, again mostly for lack of time, but it works reasonably
well. We can, and should, make incremental improvements to it, e.g. by
adding ratings. We will not introduce anything that will require complex
migration from the existing data structures.

We can of course not stop anyone from going down any of these routes,
but these sentiments are based on our previous experience at a similar
pinch-point around the time of Plone 2.1. They are endorsed by Limi,
Wiggy and various past and present members of the team.

Perhaps we can engage with some of these at a later date, but for now,
we have more urgent needs that require more immediate attention, and
some grand adventure of documentation will get in our way.

What we should do
=================

Here is a set of action points that have come out of our previous
discussions, as well as brainstorms with Alex and others.

  - Produce a documentation guide -

:: Requires: 1 volunteer to pull it together and own it

This should be a short Tutorial, and incorporate style guidelines,
structural guidelines for the main types of documentation (How-to,
tutorial, manual), and general tips on writing good documentation. A lot
of this work has been started and discussed in the past few weeks.

  - Produce templates for each type of documentation -

:: Requires: 1 volunteer to extend PHC to support documentation
templates, 1 volunteer to collect and manage the templates themselves

When a new how-to, tutorial or manual is created, it should be
pre-populated with suggested headings (for how-tos, in particular) and
sections (for tutorials and manuals), such as "Introduction", "Who is
this for?" and "Conclusion". People should be free to change this if
they feel it's appropriate. Imposing this structure on all existing
documentation i explicitly *out* of scope at this time. The purpose is
to give people a starting point, not force them into an arbitrarily
decided structure. The sections are not metadata.

  - Produce better metadata, including ratings, for documentation -

:: Requires: 1 volunteer to extend PHC to support additional metadata,
ratings

In the first instance, documentation pieces should be ratable. We should
make views that make use of ratings to highlight popular documentation.
Ratings can be as simple as "was this useful yes/no", possibly with a
third option for "is this obsolete or incorrect?". We should extend the
existing PHC stats tools to make it easier to search for "bad"
documentation that is flagged up.

We may also decide to capture additional metadata provided (a) it has a
clear purpose; (b) existing documentation does not need to be reviewed
one-by-one to make the metadata useful; and (c) it does not place
unnecessary burdens on documentation authors.

  - Produce and document ongoing documentation processes -

:: Requires: 1 volunteer to own the process documents and co-ordinate others

Currently, we work in a very ad-hoc manner. This means that things end
up staying in the plone.org review queue for a long time, for example.
It also means that we don't have a good plan when a new version of Plone
is released, we don't necessarily anticipate changes, we don't know when
and how to take things out of the documentation issue tracker, and so on.

The main "ongoing" tasks of the docs team should be documented in a
single, concise document. These practices should be lightweight and
recognise that people have limited time. They should also be followed,
and the owner of the processes should have a license to cajole people
into helping out. This also helps us answer questions like: "Hi, I'm new
here, how can I help out with documentation?" in terms of specific
actions that volunteers can take, without needing to spend a lot of time
working out how we work (if at all).

  - Produce "trails" of documentation -

:: Requires: 1 volunteer to document and promote the "trails" mechanism,
1 volunteer to choose and structure a pilot "trail", and possibly others
to contribute to the trail.

This is by far the best idea we've had, and the most concrete task. To
summarise, instead of aiming for perfection across all documentation, we
should pick up a few key topics that we reckon most members of a
particular audience would need to know. Examples may be "Connecting to
LDAP and other user sources" or "Developing new content types". This
"front-line" documentation should be thought through in more depth than
the rest of the how-tos and short tutorials.

The idea is that people have a small number of places to start from, and
can then search for more specific documentation (over which we exercise
less tight control) once they have solid fundamentals. This makes a
manageable task out of an enormous one. It is not quite as good as
starting from scratch and producing a "Plone book", but it can be more
than good enough for audiences who just want some authoritative
information, and are willing to connect some of the dots themselves.

I propose that we start with a single trail as a pilot. Whoever
volunteers for this gets to pick. A trail should be a Reference Manual
(we'll use the sections and audiences to ensure they end up on top,
possibly also a Smart Folder or template to show them more prominently).

The first step in defining a new trail is to work out the best learning
path for the intended audience and assess this against existing
documentation. From this, a workable structure of sections and
placeholder pages should be created. Some kind of gap analysis needs to
be completed to find out how the documentation we've got already matches
what we want. Then, one of four things may happen:

(1) We link to existing how-tos and tutorials from a particular page in
the trail. There will probably be a short intro with context to save
users from having to browse through documentation that happens not to be
relevant to them.

(2) We find existing documentation that's close, but not quite good
enough. We fix it up, possibly asking for help from the original authors
or experts in the community, and apply some pressure to make it happen
quickly.

(3) We solicit new documentation, either by writing it ourselves or
asking something else nicely. Again, we prioritise this work and try to
reward people for producing something in days and weeks rather than months.

(4) We leave that part of the trail blank. We can publish a trail that's
not yet fully complete if some nice-to-have sections are missing but
it's otherwise useful. Having clearly defined holes to fill help get
things completed.

I'll stop there. I'm explicitly leaving out specific such as "deal with
Plone 3", because ideally it should be a consequence of the processes we
come up with.

What now?
=========

First of all, please vote on this. Replying with a +1 or -1 is enough.

Secondly, if we agree, pick *one* task above that you'd like to
volunteer for. Don't pick more than one. When we overstretch ourselves,
we deliver nothing. Pick a task, and do what it takes to see it through
to completion. We will work with each volunteer to set a target date for
completion, and the wider community will be available to assist you (or
I'll come after them).

Thank you,
Martin


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job
easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

Donna M. Snow wrote:
> Martin (and team),
>
> I'm most interested in the "templating" aspect of this project. I may need
> some guidance as to the "right" way to do it for PHC (I haven't worked with
> PHC at all..but I've done a lot of templating).

Great :)

> -- 1 volunteer to extend PHC to support documentation templates

Bear in mind that by "templates" I don't mean Zope Page Templates, but
rather skeletal templates in the MS Word template sense. Is that what
you meant?

There are two parts to this: Extend PHC to support such templates (will
require a little bit of AT knowledge) and produce/maintain them (will
require organisational and writing skills).

Martin


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

+100 Martin :)

I will volunteer to lead the effort to get the style/documentation
guide nailed down.
Since that's winding down, I want in on the process stuff as well when
I'm finished.
As always, I'll help where ever I can if someone needs help or just
feedback. I've noticed we tend to get more progress made when we
bounce ideas off one another so I don't want that to diminish any.

On a side note: would it be possible to get a feature that would shoot
out an email to the plone-docs list when a document is submitted for
review? Would others find this helpful? Maybe we can include this with
the PHC work??


A comment on the ratings bit: lets not go as simple as yes or no. You
can find and read a document that may not be helpful to your current
situation but it doesn't mean it's a bad document at all. (does that
make sense?) Maybe a 1-5 rating system? with little stars...oooh! no.
little plone logos!! heh.


J.

-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

JoAnna Springsteen wrote:
> +100 Martin :)
>
> I will volunteer to lead the effort to get the style/documentation
> guide nailed down.

Excellent :)

> Since that's winding down, I want in on the process stuff as well when
> I'm finished.

Great. Like I said, I'd like to keep one person to one responsibility if
possible to start off with, in the interest of seeing things finished
and not overloading people.

> As always, I'll help where ever I can if someone needs help or just
> feedback. I've noticed we tend to get more progress made when we
> bounce ideas off one another so I don't want that to diminish any.

Yes, totally. In no way should these things be one-person efforts. In my
experience, things work much better when they have a single person who
"owns" the task and stakes their reputation (no pressure, just kidding)
on getting it done.

> On a side note: would it be possible to get a feature that would shoot
> out an email to the plone-docs list when a document is submitted for
> review? Would others find this helpful? Maybe we can include this with
> the PHC work??

It'd be a pretty simple change to PHC. We can roll it in with other
development.

> A comment on the ratings bit: lets not go as simple as yes or no. You
> can find and read a document that may not be helpful to your current
> situation but it doesn't mean it's a bad document at all. (does that
> make sense?) Maybe a 1-5 rating system? with little stars...oooh! no.
> little plone logos!! heh.

Yeah, we can do that. Sometimes, stars can be a bit abstract (is it five
stars for quality or relevance or lack of overlap or humour?). Perhaps
some more pointed questions? "Did this explain what you thought it was
trying to explain well?", "Did the steps work?" that kind of thing?

Martin


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Donna M Snow]

> -- 1 volunteer to extend PHC to support documentation templates

>Bear in mind that by "templates" I don't mean Zope Page Templates, but
>rather skeletal templates in the MS Word template sense. Is that what
>you meant?

Hmmm, I was thinking zpt. Is there someone else on the team who can create
these templates?
(Joanna put your hand down.. you only get to volunteer for one thing at a
time, girl :-P)

>There are two parts to this: Extend PHC to support such templates (will
>require a little bit of AT knowledge) and produce/maintain them (will
>require organisational and writing skills).

I think.. considering the fact that my "extra" time of late has been pretty
scarce.. I might work better as a "helper" .. but not as an "owner". So
rather than jumping up and saying I'll do it.. how about I provide
assistance where needed.. even if it means the more mundane work.

There are going to be times when more than one person is needed
initially..and then one person can manage that task on their own going
forward (pardon my ellipsis..I do that in email all the time).

Thanks for everything Martin! We appreciate your passion for Plone.. it's
contagious!

Best Regards,
Donna M. Snow, Owner
C Squared Enterprises
Illuminate your web
http://www.csquaredtech.com




-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

Donna M. Snow wrote:

>> -- 1 volunteer to extend PHC to support documentation templates
>
>> Bear in mind that by "templates" I don't mean Zope Page Templates, but
>> rather skeletal templates in the MS Word template sense. Is that what
>> you meant?
>
> Hmmm, I was thinking zpt. Is there someone else on the team who can create
> these templates?
> (Joanna put your hand down.. you only get to volunteer for one thing at a
> time, girl :-P)

They've already been started, in the discussions on how to structure
documentation. The first step is probably to find a developer for the
feature though (Alex Clark?).

>> There are two parts to this: Extend PHC to support such templates (will
>> require a little bit of AT knowledge) and produce/maintain them (will
>> require organisational and writing skills).
>
> I think.. considering the fact that my "extra" time of late has been pretty
> scarce.. I might work better as a "helper" .. but not as an "owner". So
> rather than jumping up and saying I'll do it.. how about I provide
> assistance where needed.. even if it means the more mundane work.
>
> There are going to be times when more than one person is needed
> initially..and then one person can manage that task on their own going
> forward (pardon my ellipsis..I do that in email all the time).

That's great. As I said to Joanna, the point is more to have someone
who's responsible than to have single-person tasks.

> Thanks for everything Martin! We appreciate your passion for Plone.. it's
> contagious!

:)

Martin


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Marco De Vitis]

On 12/02/2007 23:30, Martin Aspeli wrote:

> First of all, please vote on this. Replying with a +1 or -1 is enough.

+1 on everything here.

I currently am not able to volunteer for anything (other stuff is
keeping me away from Plone at the moment, and probably will for another
month or so), but I'll be here to review and annoy to my best ;).

--
Ciao,
   Marco.


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Christian Schneider-10]

Hey all,
I finally found some time to read this novel of optilude and kind of
understand it ;). I agree with most things, but to me it feels like the
"What we are not doing" section is a bit too harsh and actually somewhat
contradicts the goals we're going for:

>   - We should not go down any route that involve re-writing all the
> documentation.

I think no-one wanted to go down that route really... neither did anyone
want to dump the existing docs and re-do them or have them re-submitted.

>   - We should not go down any route that requires in-depth editorial
> review of every piece of documentation. We did that once, with a larger
> team than this one and a quarter as many pieces of documentation, and it
> took months just to get back to something which was as good as the what
> we had before.

That depends on what "in-depth editorial" means. I think some pieces of
documentation that are in the doc area shouldn't really be out there at
all, so I think that a somewhat stricter editing process wouldn't be a
bad thing.

>   - We should not require every documentation author to re-do and
> re-submit their work. We may choose to edit or retract some bad
> documentation, and offer authors the chance to try again, but it is
> unrealistic to expect people to have time to re-do documentation they
> feel they've already given the community. This is doubly dangerous,
> because it risks alienating the very people who's support we need.

Again, I think no-one wanted to go that way.

>   - We should not segregate documentation so clearly that a large number
> of people who've contributed documentation feels their efforts are
> marginalised and thus not worth the effort.

In a way you're asking for just that when you say you want some things
to be in a trail (you referred to them as "blessed" docs at some point)
and I think that's actually a good thing to do.

>   - We will not invent radically new technology. The PHC has taken years
> to be complete, again mostly for lack of time, but it works reasonably
> well. We can, and should, make incremental improvements to it, e.g. by
> adding ratings. We will not introduce anything that will require complex
> migration from the existing data structures.
> ...
> Perhaps we can engage with some of these at a later date, but for now,
> we have more urgent needs that require more immediate attention, and
> some grand adventure of documentation will get in our way.

Again, no-one suggested rewriting PHC, but as you say yourself later,
PHC will get extended and some changes can be incorporated along the
way. This organic growth/evolution is a good thing, but we should
seriously think about (and that's all we did) what an "ideal" doc-area
would look like, just to be able to make sure that the PHC doesn't
evolve into crap. We need a goal to aim for and collect and discuss
ideas for that, after all Plone and therefore the need for good
documentation is not very likely to die anytime soon, so having
long-term plans can not be a bad thing.


In the following "What we should do" section you say that imposing a
certain structure on all existing documentation is out of the scope at
this time. But what about the newly added and newly edited docs that
will end up in the learning trails? Don't you think these could and
should be best practice examples of how good Plone documentation should
look? And I think you fail to see that the trails as being "our best
idea" are the basis for all the other things that the we have discussed
in the chat and on the wiki... organizing stuff in trails REQUIRES a
certain structure for things that are in the trail, or you will end up
with an incoherent, ill-structured mess with links. Joanna is on a very
good way with the structural guideline and I'd be hard pressed to call
this "arbitrarily decided"... she's a technical writer after all.

>   - Produce "trails" of documentation -
>
> :: Requires: 1 volunteer to document and promote the "trails" mechanism,
> 1 volunteer to choose and structure a pilot "trail", and possibly others
> to contribute to the trail.
>
> This is by far the best idea we've had, and the most concrete task. To
> summarise, instead of aiming for perfection across all documentation, we
> should pick up a few key topics that we reckon most members of a
> particular audience would need to know. Examples may be "Connecting to
> LDAP and other user sources" or "Developing new content types". This
> "front-line" documentation should be thought through in more depth than
> the rest of the how-tos and short tutorials.

+10000

> I propose that we start with a single trail as a pilot. Whoever
> volunteers for this gets to pick. A trail should be a Reference Manual
> (we'll use the sections and audiences to ensure they end up on top,
> possibly also a Smart Folder or template to show them more prominently).

I'd like to pick up that one if no-one else has already (should we
create a wiki-page for the responsibilities or are we having enough
wikis already ;o). As for the subject I'll think about a couple of
topics and propose them tomorrow evening in the doc chat.

> The first step in defining a new trail is to work out the best learning
> path for the intended audience and assess this against existing
> documentation. From this, a workable structure of sections and
> placeholder pages should be created. Some kind of gap analysis needs to
> be completed to find out how the documentation we've got already matches
> what we want. Then, one of four things may happen:
>
> (1) We link to existing how-tos and tutorials from a particular page in
> the trail. There will probably be a short intro with context to save
> users from having to browse through documentation that happens not to be
> relevant to them.
>
> (2) We find existing documentation that's close, but not quite good
> enough. We fix it up, possibly asking for help from the original authors
> or experts in the community, and apply some pressure to make it happen
> quickly.

I guess this is will most often be the case. I'd really like to have
stuff that enters the trails structured according to Joanna's style
guide. Having sections as headers only is fine with me (but debatable
for the future), and I guess that while trying to structure things that
go into the trails we will find shortcommings of the guidelines and can
fix them before others get to read them.

> (3) We solicit new documentation, either by writing it ourselves or
> asking something else nicely. Again, we prioritise this work and try to
> reward people for producing something in days and weeks rather than
months.
>
> (4) We leave that part of the trail blank. We can publish a trail that's
> not yet fully complete if some nice-to-have sections are missing but
> it's otherwise useful. Having clearly defined holes to fill help get
> things completed.

That's what I started the "Map" on openplans for a while back, to be
able to collect topics that should be covered, and then organize them in
a meaningful way and see where there are holes to fill.

Toodles for now
Christian


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

>>   - We should not go down any route that involve re-writing all the
>> documentation.
>
> I think no-one wanted to go down that route really... neither did anyone
> want to dump the existing docs and re-do them or have them re-submitted.

Yes, yes, I know, I just wanted to be explicit about a few things.

>>   - We should not go down any route that requires in-depth editorial
>> review of every piece of documentation. We did that once, with a larger
>> team than this one and a quarter as many pieces of documentation, and it
>> took months just to get back to something which was as good as the what
>> we had before.
>
> That depends on what "in-depth editorial" means. I think some pieces of
> documentation that are in the doc area shouldn't really be out there at
> all, so I think that a somewhat stricter editing process wouldn't be a
> bad thing.

Review is great, as is having a well-documented review process. A bit
stricter is probably good, but it's difficult to get the right balance.
The average review time on plone.org is "too long" and it's often hard
for those who want to / have time to review to know enough about the
topic to review it properly. Again, I think the biggest win here will be
to have well-defined editorial guidelines.

>>   - We should not require every documentation author to re-do and
>> re-submit their work. We may choose to edit or retract some bad
>> documentation, and offer authors the chance to try again, but it is
>> unrealistic to expect people to have time to re-do documentation they
>> feel they've already given the community. This is doubly dangerous,
>> because it risks alienating the very people who's support we need.
>
> Again, I think no-one wanted to go that way.

Yep.

>>   - We should not segregate documentation so clearly that a large number
>> of people who've contributed documentation feels their efforts are
>> marginalised and thus not worth the effort.
>
> In a way you're asking for just that when you say you want some things
> to be in a trail (you referred to them as "blessed" docs at some point)
> and I think that's actually a good thing to do.

Yes, true. I guess it's a matter of degrees. I think "blessing" some
"important" documentation is easier to tell to people than "all of this
is deprecated or will be deleted and all new stuff goes here". I think
we agree on this, though.

>>   - We will not invent radically new technology. The PHC has taken years
>> to be complete, again mostly for lack of time, but it works reasonably
>> well. We can, and should, make incremental improvements to it, e.g. by
>> adding ratings. We will not introduce anything that will require complex
>> migration from the existing data structures.
>> ...
>> Perhaps we can engage with some of these at a later date, but for now,
>> we have more urgent needs that require more immediate attention, and
>> some grand adventure of documentation will get in our way.
>
> Again, no-one suggested rewriting PHC, but as you say yourself later,
> PHC will get extended and some changes can be incorporated along the
> way. This organic growth/evolution is a good thing, but we should
> seriously think about (and that's all we did) what an "ideal" doc-area
> would look like, just to be able to make sure that the PHC doesn't
> evolve into crap. We need a goal to aim for and collect and discuss
> ideas for that, after all Plone and therefore the need for good
> documentation is not very likely to die anytime soon, so having
> long-term plans can not be a bad thing.

Yes, of course. However, I'm pretty sure that the PHC is not radically
"wrong" at the moment. So, changing the documentation categories (or
abolishing them) would be a lot of work and hellish migration, as would
the idea of reconceptualising documentation as assemblies of smaller
pieces (I also don't believe this would work practically).

> In the following "What we should do" section you say that imposing a
> certain structure on all existing documentation is out of the scope at
> this time. But what about the newly added and newly edited docs that
> will end up in the learning trails? Don't you think these could and
> should be best practice examples of how good Plone documentation should
> look? And I think you fail to see that the trails as being "our best
> idea" are the basis for all the other things that the we have discussed
> in the chat and on the wiki... organizing stuff in trails REQUIRES a
> certain structure for things that are in the trail, or you will end up
> with an incoherent, ill-structured mess with links. Joanna is on a very
> good way with the structural guideline and I'd be hard pressed to call
> this "arbitrarily decided"... she's a technical writer after all.

Yes. My position has always been that structure should be strongly
encouraged, but not enforced. So, specifically, what I want is that when
you create a HowTo, you get pre-populated body text which suggests an
outline. People may choose to ignore that, but the editorial guidelines
should suggest that if people choose to ignore our suggestions outright,
then we review the document for readability more carefully.

A suggestion was floated that we turn the structural guidelines into
fields on the how-to. This is what I'm trying to avoid, for a few reasons:

  - People who have nothing intelligent to put there will ignore it or
just put junk in there.

  - People who write text offline don't want to work this way, and will
paste their text into the biggest field.

  - Existing documents won't have it.

  - When we change our minds on which fields there are, we have a
hellish migration exercise to move the persistent state from the old
schema to the new schema.

  - Maintaining the "skeleton" through-the-web is easy; in Archetypes it
is not.

  - It adds very little value. We are not going to search on these
individually. They are free text, and having one free text field is just
as useful as having many, since it's only SearchableText that matters
for non-metadata search.

We *do* have metadata: tags/keywords, audience, version compatability.
These are useful because we can search on them, and because we want them
to be selected from lists rather than typed in free text.

And I disagree that all content has to strictly conform to the same
format to be "good" or useful. We will never have 100% consistent
documentation, because it's all written by different people who have
various degrees of comfort writing in English. To the end user, that's a
secondary concern, so long as the documentation is clear and
understandable.

For our "blessed" documentation, we will be more anal about style and
structure, of course.

>>   - Produce "trails" of documentation -
>>
>> :: Requires: 1 volunteer to document and promote the "trails" mechanism,
>> 1 volunteer to choose and structure a pilot "trail", and possibly others
>> to contribute to the trail.
>>
>> This is by far the best idea we've had, and the most concrete task. To
>> summarise, instead of aiming for perfection across all documentation, we
>> should pick up a few key topics that we reckon most members of a
>> particular audience would need to know. Examples may be "Connecting to
>> LDAP and other user sources" or "Developing new content types". This
>> "front-line" documentation should be thought through in more depth than
>> the rest of the how-tos and short tutorials.
>
> +10000

:)

>> I propose that we start with a single trail as a pilot. Whoever
>> volunteers for this gets to pick. A trail should be a Reference Manual
>> (we'll use the sections and audiences to ensure they end up on top,
>> possibly also a Smart Folder or template to show them more prominently).
>
> I'd like to pick up that one if no-one else has already (should we
> create a wiki-page for the responsibilities or are we having enough
> wikis already ;o). As for the subject I'll think about a couple of
> topics and propose them tomorrow evening in the doc chat.

Great!

>> The first step in defining a new trail is to work out the best learning
>> path for the intended audience and assess this against existing
>> documentation. From this, a workable structure of sections and
>> placeholder pages should be created. Some kind of gap analysis needs to
>> be completed to find out how the documentation we've got already matches
>> what we want. Then, one of four things may happen:
>>
>> (1) We link to existing how-tos and tutorials from a particular page in
>> the trail. There will probably be a short intro with context to save
>> users from having to browse through documentation that happens not to be
>> relevant to them.
>>
>> (2) We find existing documentation that's close, but not quite good
>> enough. We fix it up, possibly asking for help from the original authors
>> or experts in the community, and apply some pressure to make it happen
>> quickly.
>
> I guess this is will most often be the case. I'd really like to have
> stuff that enters the trails structured according to Joanna's style
> guide. Having sections as headers only is fine with me (but debatable
> for the future), and I guess that while trying to structure things that
> go into the trails we will find shortcommings of the guidelines and can
> fix them before others get to read them.

Yes, that's the process I envisaged. I think we should be pragmatic and
fix the things that are worst (or outright missing) first, and the
things that are only slightly wrong last.

>> (3) We solicit new documentation, either by writing it ourselves or
>> asking something else nicely. Again, we prioritise this work and try to
>> reward people for producing something in days and weeks rather than
> months.
>> (4) We leave that part of the trail blank. We can publish a trail that's
>> not yet fully complete if some nice-to-have sections are missing but
>> it's otherwise useful. Having clearly defined holes to fill help get
>> things completed.
>
> That's what I started the "Map" on openplans for a while back, to be
> able to collect topics that should be covered, and then organize them in
> a meaningful way and see where there are holes to fill.

Great! I suggest we just start with ref manuals. We can all see them
anyway, and if we do it first in a wiki and then in a manual we have to
do it twice. :)

Martin


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

For those who are available- Lets talk about all this stuff on Sunday.
Whatever time we usually do it at...3CST for me. (sorry I'm lazy and
not converting today).


We should also talk about interest in a (physical) doc sprint. If you
don't subscribe to the plone-users list you can see that email here:
http://groups.google.com/group/plone-users/browse_thread/thread/a69134af58aaa5db


J.

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

JoAnna Springsteen wrote:
> For those who are available- Lets talk about all this stuff on Sunday.
> Whatever time we usually do it at...3CST for me. (sorry I'm lazy and
> not converting today).
>
>
> We should also talk about interest in a (physical) doc sprint. If you
> don't subscribe to the plone-users list you can see that email here:
> http://groups.google.com/group/plone-users/browse_thread/thread/a69134af58aaa5db


I'll be around, but I won't be in the channel talking, because of stuff
happening here in Baarn.

Martin


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

Wanted to respond to this real quick:

> In the following "What we should do" section you say that imposing a
> certain structure on all existing documentation is out of the scope at
> this time. But what about the newly added and newly edited docs that
> will end up in the learning trails? Don't you think these could and
> should be best practice examples of how good Plone documentation should
> look? And I think you fail to see that the trails as being "our best
> idea" are the basis for all the other things that the we have discussed
> in the chat and on the wiki... organizing stuff in trails REQUIRES a
> certain structure for things that are in the trail, or you will end up
> with an incoherent, ill-structured mess with links. Joanna is on a very
> good way with the structural guideline and I'd be hard pressed to call
> this "arbitrarily decided"... she's a technical writer after all.

In an ideal world, all of our documentation would be gorgeous and
everyone would follow best standards. For the most part in my job, I
have enough control to enforce this. But in open source, it's not the
same environment (thank goodness).

We need people to write docs. If it means that they dump their
knowledge onto the page and then someone edits to put it in our
preferred format and style- I'm willing to do that. (not on every doc
but those that are badly needed or when I have time)

Don't get caught up in the word structure. When I talk about
structure, I'm not talking about any kind of coding, etc. While a
trail will need structure, it's more about identifying a path and then
figuring out how to string things together. If we want to get in on a
discussion on how to do this, Reference Manuals are probably our best
bet.

Rob's comment saddens me. I don't want people to feel like they can't
contribute because we're debating (or for any other reason). This is
exactly what we want to avoid!!

martin- go to bed!!!
and also put those sprint doc tasks in the tracker if they aren't already ;)

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Christian Schneider-10]

Ok, thanks for clearing things up. Now I get what you mean and I totally
agree.
As for the reference manual stuff, you mean that I should just set up a
few of those and put in dummies that describe what will be covered once
the manual is fleshed out, right?
I'll see what I can come up with...
I won't be on until late sunday evening, I guess after 11pm CET... no
clue what that is for the others though.
See you then hopefully
Christian


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

Christian Schneider wrote:
> Ok, thanks for clearing things up. Now I get what you mean and I totally
> agree.
> As for the reference manual stuff, you mean that I should just set up a
> few of those and put in dummies that describe what will be covered once
> the manual is fleshed out, right?
> I'll see what I can come up with...

I think if you take the lead on this, then why not? If you prefer
working on the wiki, then do, but eventually, they'll need to be there,
and we have the tools to make "outlines" of pages and sections....

Martin


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

This is your not so gentle, yet oh so friendly, reminder to respond to
Martin's message. Please post your thoughts as we want to hear what
you have to say, even if you're busy or haven't been active, or
whatever.
We still have lots of items that Martin outlined that haven't been
picked up. So even if you can't lead the effort, at least let us know
what you'd be willing to work on.

J.

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Sisi Nutt]

Martin Aspeli wrote:

> First of all, please vote on this. Replying with a +1 or -1 is enough.

+1
(sorry my voting is late... thanks to JoAnna for sending the reminder)

I'd like to volunteer for something but not right now. I want to
concentrate on the migration docs and the core developer docs for the
upcoming plone 3 release.

Cheers,
sisi

--
# sisi nutt # extranet coordinator
# Friends of the Earth International
# PO Box 19199 # 1000 GD Amsterdam # The Netherlands
# Tel [phone]  # Fax [phone]  # http://www.foei.org
# email [hidden email] # skype foei_sisi

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Jan Ulrich Hasecke]

Hi Martin,

I fully agree with your proposal. Just three remarks from a lurking
position.

1. The rating thing is a good idea. It would be great, if it is generic
and usable for all Plone content.

2. I am not sure whether this is the right thread for this proposal, but
I think we need a better sorting of the products section on plone.org

At the first glance you should see, whether a product runs on Plone 2.X
or not.

3. Beginning with Plone 3.0 I would like to see an "upgrade-save" ribbon
next to each product, which upgrades well from 2.5 to 3.0

No user should ever try to upgrade a plone site with products that will
break the whole site after upgrading.

The rational for this is: outside the Plone Community rumours are
spreading fast, that you shall never upgrade a plone site unless you
want to start from scratch.

Breaking products are contraband to Plone marketing.


juh

--
Jan Ulrich Hasecke
Mitglied im Vorstand des DZUG e.V.
(Deutschsprachige Zope User Group)


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[David Sapiro - Pilot Systems]

Hi,

Le 6 mars 07 à 11:35, Jan Ulrich Hasecke a écrit :

> Hi Martin,
>
> I fully agree with your proposal. Just three remarks from a lurking
> position.
>
> 1. The rating thing is a good idea. It would be great, if it is  
> generic
> and usable for all Plone content.
>
> 2. I am not sure whether this is the right thread for this  
> proposal, but
> I think we need a better sorting of the products section on plone.org
>
> At the first glance you should see, whether a product runs on Plone  
> 2.X
> or not.
>
> 3. Beginning with Plone 3.0 I would like to see an "upgrade-save"  
> ribbon
> next to each product, which upgrades well from 2.5 to 3.0
>
> No user should ever try to upgrade a plone site with products that  
> will
> break the whole site after upgrading.
>
> The rational for this is: outside the Plone Community rumours are
> spreading fast, that you shall never upgrade a plone site unless you
> want to start from scratch.
>
> Breaking products are contraband to Plone marketing.

I fullt agree on this - again - :)

On my do list, I have specs + implementation manpower for the PSC,  
but didn't make it yet. Too bad. This is related to a couple month  
old discussion we had.

FYI, I just hang the phone with one of our big customer, that is  
starting to be really pissed off about the upgrading situation and  
that is considering migrating to another CMS / SW because of the lack  
of upgrading capacity of Plone in genral. This includes : Plone Core,  
Main Addons, templating work and of course these stupid specific dev  
that makes the managers happy because they have their "baby" system  
and not the one that is maintainable. Of course, this is easy to say,  
I agree. But this is a fact out there, and we must face it in a way  
or another.

A bit of topic, but a direct answer to your mail.

Dave



--
David Sapiro - [hidden email]
Pilot Systems - 9, rue Desargues - 75011 Paris
Tel : [phone] - http://www.pilotsystems.net
Hébergement Zope et Plone gratuit - http://www.objectis.org



-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli-2]

Jan Ulrich Hasecke wrote:
> Hi Martin,
>
> I fully agree with your proposal. Just three remarks from a lurking
> position.
>
> 1. The rating thing is a good idea. It would be great, if it is generic
> and usable for all Plone content.

Yes. I'd like to use 'contentratings' which is generic.

> 2. I am not sure whether this is the right thread for this proposal, but
> I think we need a better sorting of the products section on plone.org
>
> At the first glance you should see, whether a product runs on Plone 2.X
> or not.

Wrong thread, but this kind of thinking is at
http://openplans.org/projects/plone-products and is in line with what
we've talked about.

> 3. Beginning with Plone 3.0 I would like to see an "upgrade-save" ribbon
> next to each product, which upgrades well from 2.5 to 3.0

Heh, nice idea. We *do* have a way of marking which Plone version a
product works with though. Again, wrong thread (and mailing list)
though. plone-website is better.

Martin


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs