[Plone-docs] how to contribute docs

Discussion:

John Schinnerer

2010-01-13 20:44:09 UTC

Hello,

I have at least one how-to to contribute on an issue I recently dealt
with. Hopefully other contributions going forward.

Plone.org (including docs organization) has changed radically since I
last contributed. I can no longer find where to go simply to add a
how-to. I have gone in circles on the 'how to contribute' section of the
docs pages.
Also it seems no longer possible to comment existing docs with
additional information and/or corrections.

Any assistance appreciated!

thanks,
John S.

--
John Schinnerer - M.A., Whole Systems Design
--------------------------------------------
- Eco-Living -
Whole Systems Design Services
People - Place - Learning - Integration
***@eco-living.net
http://eco-living.net

Veda Williams

2010-01-13 22:44:15 UTC

Permalink

Hi there John,

First, comments on documents have been removed, as they were becoming
cluttered and hard to maintain.

My suggestion is that you give someone on the doc team your Plone.org
username, and you can be granted rights to contribute to the "knowledgebase"
area (http://plone.org/documentation/kb). This is a new space that is
intended to be more of an open edit space (once the full migration is done
and permissions are set up), and it's the place where the doc team expects
new how-tos and tutorials to be contributed.

Israel / Steve, can one of you grant John rights to this area? I assume this
isn't a problem to do so?

Thanks,

- Veda

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

ONE/Northwest is now Groundwire!

John Schinnerer

2010-01-14 00:20:57 UTC

Permalink

Hello,

Thanks for the quick reply.
Sounds like what I need to do then...request perms in the kb
section...so, can I please be a contributor?
Username is:

jschinnerer

Any questions or need more info, let me know...
thanks,
John S.

Post by Veda Williams
Hi there John,
First, comments on documents have been removed, as they were becoming
cluttered and hard to maintain.
My suggestion is that you give someone on the doc team your Plone.org
username, and you can be granted rights to contribute to the "knowledgebase"
area (http://plone.org/documentation/kb). This is a new space that is
intended to be more of an open edit space (once the full migration is done
and permissions are set up), and it's the place where the doc team expects
new how-tos and tutorials to be contributed.
Israel / Steve, can one of you grant John rights to this area? I assume this
isn't a problem to do so?
Thanks,
- Veda

David Hostetler

2010-01-15 20:58:50 UTC

Permalink

Post by Veda Williams
Hi there John,
First, comments on documents have been removed, as they were becoming
cluttered and hard to maintain.

I'm dismayed by that. Some of the most invaluable nuggets of info I've ever
found when dealing with Plone were comments added to documents on plone.org.
I might suggest that the problem isn't that comments are 'hard to
maintain' but rather that frequently the documents themselves were utterly
abandoned, and people other than the original author were the ones keeping
the information relevant via the comment thread.

My perspective on commentable documents is that the documents are supposed
to be 'living authored content' and that the comments represent a staging
area for feedback/information that needs to be assimilated into the
document. If the original author can't/won't do that, then the document
itself needs to be editable by those who are investing the time/energy into
adding the comments.

I totally agree that comments on the plone.org documents should not be used
as an ad hoc support forum. But just turning off commenting wholesale
throws the baby out with the bathwater.

What good is a dynamic CMS if not for allowing documentation to be refined
over time and remain germane to its intended audience?

regards,

-David

John Schinnerer

2010-01-15 21:13:47 UTC

Permalink

Aloha,

Post by Veda Williams
First, comments on documents have been removed, as they were becoming
cluttered and hard to maintain.
I'm dismayed by that. Some of the most invaluable nuggets of info I've
ever found when dealing with Plone were comments added to documents on
plone.org <http://plone.org>.

Ditto on that...
Also agree that some other design(s) could serve better than the old ad
hoc comments or the new no comments at all.
Ad hoc got messy and sometimes off-track; no comments really limits ease
of providing small but essential bits of information.

Post by Veda Williams
My perspective on commentable documents is that the documents are
supposed to be 'living authored content' and that the comments represent
a staging area for feedback/information that needs to be assimilated
into the document. If the original author can't/won't do that, then the
document itself needs to be editable by those who are investing the
time/energy into adding the comments.

...so I think you are some kind of shared contribute/edit abilities that
can be applied in cases where an original author no longer maintains a
doc (by integrating comments/updating) and no other individual steps in
to take over primary responsibility, which seems like one reasonable option.

thanks,
John S.

Alexander Limi

2010-01-15 22:24:23 UTC

Permalink

Post by David Hostetler
I'm dismayed by that. Some of the most invaluable nuggets of info I've
ever found when dealing with Plone were comments added to documents on
plone.org. I might suggest that the problem isn't that comments are
'hard to maintain' but rather that frequently the documents themselves were
utterly abandoned, and people other than the original author were the ones
keeping the information relevant via the comment thread.

Right. The new approach is:

- If it's in the Knowledge Base, you can edit it directly to fix things
(or contact the author, of course your choice)
- If it's in the official manuals, you file a ticket, and the editors
will fix it.

It's not to discourage comments, but if you look around on other open source
projects, they have the same problem comments always turn into ad-hoc
support and/or discussion. This confuses people that are new, and annoys
people that know better. For what it's worth, several other open source
projects are moving in the same direction (I think jQuery just did the same
thing to avoid the same issue).

What good is a dynamic CMS if not for allowing documentation to be refined

Post by David Hostetler
over time and remain germane to its intended audience?

Totally agree, and that's why we'll have a more open editing policy in the
KB area once the transition is complete. As Veda mentioned, it still needs
some work, and I'm as guilty as any in not finishing my redesign tasks yet
on the UI side of things. But it's a priority, right now I'm head down in
Plone 4, but hope to get to it ASAP.

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

David Hostetler

2010-01-15 22:40:34 UTC

Permalink

Roger that. Thanks to all for the follow-up replies. My concerns are
completely moot with a KB that can be collaboratively edited - I just hadn't
heard about that policy yet.

And the distinction between KB content and a small set of official (and
officially maintained) documentation is a good one that will benefit Plone
tremendously.

regards,

-David

Post by Alexander Limi

- If it's in the Knowledge Base, you can edit it directly to fix things
(or contact the author, of course â your choice)
- If it's in the official manuals, you file a ticket, and the editors
will fix it.
It's not to discourage comments, but if you look around on other open
source projects, they have the same problem â comments always turn into
ad-hoc support and/or discussion. This confuses people that are new, and
annoys people that know better. For what it's worth, several other open
source projects are moving in the same direction (I think jQuery just did
the same thing to avoid the same issue).
What good is a dynamic CMS if not for allowing documentation to be refined

Post by David Hostetler
over time and remain germane to its intended audience?

John Schinnerer

2010-01-16 20:38:43 UTC

Permalink

+1 on this approach - sounds like a good balance of control and chaos... :-)

John S.

Post by David Hostetler
I'm dismayed by that. Some of the most invaluable nuggets of info
I've ever found when dealing with Plone were comments added to
documents on plone.org <http://plone.org>. I might suggest that
the problem isn't that comments are 'hard to maintain' but rather
that frequently the documents themselves were utterly abandoned, and
people other than the original author were the ones keeping the
information relevant via the comment thread.
* If it's in the Knowledge Base, you can edit it directly to fix
things (or contact the author, of course — your choice)
* If it's in the official manuals, you file a ticket, and the
editors will fix it.
It's not to discourage comments, but if you look around on other open
source projects, they have the same problem — comments always turn into
ad-hoc support and/or discussion. This confuses people that are new, and
annoys people that know better. For what it's worth, several other open
source projects are moving in the same direction (I think jQuery just
did the same thing to avoid the same issue).
What good is a dynamic CMS if not for allowing documentation to be
refined over time and remain germane to its intended audience?
Totally agree, and that's why we'll have a more open editing policy in
the KB area once the transition is complete. As Veda mentioned, it still
needs some work, and I'm as guilty as any in not finishing my redesign
tasks yet on the UI side of things. But it's a priority, right now I'm
head down in Plone 4, but hope to get to it ASAP.
--
Alexander Limi · http://limi.net
------------------------------------------------------------------------
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts the
world's best and brightest in the field, creating opportunities for Conference
attendees to learn about information security's most important issues through
interactions with peers, luminaries and emerging and established companies.
http://p.sf.net/sfu/rsaconf-dev2dev
------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

Alexander Limi

2010-01-14 00:26:58 UTC

Permalink

You are also coming to it in the middle of an upgrade, so there's still some
dust left. :)

Post by John Schinnerer
Hello,
I have at least one how-to to contribute on an issue I recently dealt
with. Hopefully other contributions going forward.
Plone.org (including docs organization) has changed radically since I
last contributed. I can no longer find where to go simply to add a
how-to. I have gone in circles on the 'how to contribute' section of the
docs pages.
Also it seems no longer possible to comment existing docs with
additional information and/or corrections.
Any assistance appreciated!
thanks,
John S.
--
John Schinnerer - M.A., Whole Systems Design
--------------------------------------------
- Eco-Living -
Whole Systems Design Services
People - Place - Learning - Integration
http://eco-living.net
------------------------------------------------------------------------------
This SF.Net email is sponsored by the Verizon Developer Community
Take advantage of Verizon's best-in-class app development support
A streamlined, 14 day to market process makes app distribution fast and
easy
Join now and get one step closer to millions of Verizon customers
http://p.sf.net/sfu/verizon-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

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

Veda Williams

2010-01-15 19:58:08 UTC

Permalink

Hi John,

I think there may currently be a problem with saving documents on plone.org,
so giving you rights at the moment may not help you.

SteveM, can you say whether there is indeed an issue for this and when we
can expect it to be resolved?

Thanks,

- Veda

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

ONE/Northwest is now Groundwire!

Alexander Limi

2010-01-15 20:40:27 UTC

Permalink

I should have been resolved a while back if you're talking about the UID
errors?

Alex

Post by Veda Williams
Hi John,
I think there may currently be a problem with saving documents on plone.org,
so giving you rights at the moment may not help you.
SteveM, can you say whether there is indeed an issue for this and when we
can expect it to be resolved?
Thanks,
- Veda

--
Veda Williams
Web Developer
Groundwire
206.286.1235x23
http://groundwire.org
ONE/Northwest is now Groundwire!
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts the
world's best and brightest in the field, creating opportunities for
Conference
attendees to learn about information security's most important issues
through
interactions with peers, luminaries and emerging and established companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

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

Veda Williams

2010-01-15 21:11:44 UTC

Permalink

Looks like it:

https://dev.plone.org/plone/ticket/9984

Thanks!

Post by Alexander Limi
I should have been resolved a while back if you're talking about the UID
errors?
<Alex

Post by Veda Williams
Hi John,
I think there may currently be a problem with saving documents on plone.org
<http://plone.org> ,
so giving you rights at the moment may not help you.
SteveM, can you say whether there is indeed an issue for this and when we
can expect it to be resolved?
Thanks,
- Veda

--
Veda Williams
Web Developer
Groundwire
206.286.1235x23
http://groundwire.org
ONE/Northwest is now Groundwire!

----------------------------------------------------------------------------->>
-

Post by Alexander Limi

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

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

ONE/Northwest is now Groundwire!

Veda Williams

2010-01-15 21:14:40 UTC

Permalink

Hi John,

The idea is that the kb will be mostly open edit and so if people have a
comment, per se, they just update the document themselves. And, there will
be a link to submit tickets to the doc team in the manuals. We¹re just not
done with the migration that will allow for all of this, but it¹s in
progress.... The goal is to make sure these nuggets get incorporated, but
that the responsibility doesn¹t necessarily fall on the original author to
maintain the docs.

Post by David Hostetler

Post by Veda Williams
Hi there John,
First, comments on documents have been removed, as they were becoming
cluttered and hard to maintain.

I'm dismayed by that. Some of the most invaluable nuggets of info I've ever
found when dealing with Plone were comments added to documents on plone.org
<http://plone.org> . I might suggest that the problem isn't that comments
are 'hard to maintain' but rather that frequently the documents themselves
were utterly abandoned, and people other than the original author were the
ones keeping the information relevant via the comment thread.
My perspective on commentable documents is that the documents are supposed to
be 'living authored content' and that the comments represent a staging area
for feedback/information that needs to be assimilated into the document. If
the original author can't/won't do that, then the document itself needs to be
editable by those who are investing the time/energy into adding the comments.
I totally agree that comments on the plone.org <http://plone.org> documents
should not be used as an ad hoc support forum. But just turning off
commenting wholesale throws the baby out with the bathwater.
What good is a dynamic CMS if not for allowing documentation to be refined
over time and remain germane to its intended audience?
regards,
-David

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

ONE/Northwest is now Groundwire!

Veda Williams

2010-01-15 21:20:24 UTC

Permalink

Open edit in the KB area should help... Once we get there. It's just taking
longer than we anticipated, and there has been a real shortage of time and
people to work on this. But yes, what you're asking for is in progress...

Post by John Schinnerer
Aloha,