Dylan Jay
2012-03-27 23:31:03 UTC
Date: 27 March 2012 5:52:28 PM
Subject: Report from Cioppino Sprint 2012
Source: Planet Plone
Author: David Glick
I've just returned from yet another memorable Plone event, the 2nd
annualCioppino Sprint. For the past 4 days, twelve of us gathered at
a house in lovely Bodega Bay, CA for a weekend of fun, relaxation,
and giving back to the Plone community.
The theme of the sprint was improving Plone's documentation and
community infrastructure. On the first evening we gathered to
brainstorm tasks,
... <cool stuff that was done snipped> ...Subject: Report from Cioppino Sprint 2012
Source: Planet Plone
Author: David Glick
I've just returned from yet another memorable Plone event, the 2nd
annualCioppino Sprint. For the past 4 days, twelve of us gathered at
a house in lovely Bodega Bay, CA for a weekend of fun, relaxation,
and giving back to the Plone community.
The theme of the sprint was improving Plone's documentation and
community infrastructure. On the first evening we gathered to
brainstorm tasks,
Really exciting to see so much effort put into documentation.
One thing that did not happen at the sprint was a clear designation
of a revitalized documentation team to make sure that our
documentation is well-managed on an ongoing basis. Personally I feel
that this is a role that is lacking in the community—Mikko and
others are doing a fantastic job of getting people to add and update
documentation in the collective developer manual, but I there is a
need for a more focused manual and introductory documentation for
people who are trying to learn Plone development for the first time
rather than looking up particular tasks or topics—communally edited
documentation is inevitably of varying quality and relevance, and
newbies have no way to judge that. There is also a need to make sure
that old documents are updated or marked as obsolete as appropriate.
It's not entirely surprising that we've lacked this editing, as it
is a thankless task (everyone can get excited about new
documentation; someone always hates you when you delete something).
I don't have answers but I hope we can brainstorm as a community
about how to solve this problem (or maybe you can convince me I've
diagnosed the wrong problem.)
I've got a couple of ideas :)of a revitalized documentation team to make sure that our
documentation is well-managed on an ongoing basis. Personally I feel
that this is a role that is lacking in the community—Mikko and
others are doing a fantastic job of getting people to add and update
documentation in the collective developer manual, but I there is a
need for a more focused manual and introductory documentation for
people who are trying to learn Plone development for the first time
rather than looking up particular tasks or topics—communally edited
documentation is inevitably of varying quality and relevance, and
newbies have no way to judge that. There is also a need to make sure
that old documents are updated or marked as obsolete as appropriate.
It's not entirely surprising that we've lacked this editing, as it
is a thankless task (everyone can get excited about new
documentation; someone always hates you when you delete something).
I don't have answers but I hope we can brainstorm as a community
about how to solve this problem (or maybe you can convince me I've
diagnosed the wrong problem.)
One of the things you said David on #sprint really hit home. Both the
knowledgebase and the c.dm can suffer from the following problem. That
people feel they have the authority to add and correct, but often not
to delete, reorganise and merge content. The consequence is c.dm will
make less and less sense read end to end over time, which is a shame
as the real advantage c.dm has over the KB is its "browsability". What
I mean by "browsability" is that I can find what I'm looking for by
scrolling up and down and also navigating within the same section,
rather than relying purely on google.
I think solving the authority problem is what will prevent c.dm
becoming a dumping ground like the KB is.
Here's an idea to kick off discussion:
Have a team of 2-3 who have the authority to consolidate c.dm. This
doesn't mean they are the only ones that do that work, just that it
gives you someone to ask your proposed restructure is a good idea or
not. Think of it as a kind of FWT for c.dm.
As an example I've thought for a long time we should rename the
"tutorials" section to "Introduction to Plone's Architecture" and then
move anything in there that doesn't fit to where it does fit, such as
AGX into the content section. I feel I need to ask permission to make
such a change but it's currently unclear who to ask and hence I've
left it. Exactly the behaviour David described. If instead we had a
small team with a joint vision of where the manual is going, I'd just
put my proposed changes to them via this list and they can make that
decision.
Would this work? or is it overkill?
Also, I think another thing that would help is some kind of mechanism
of redirecting from the old location of moved content. Does RTD
support this?