Re: [Plone-docs] Brainstorming next PHC

[Dylan J. <dy...@dy...>]

Hi,

I do agree the PHC types don't help much. Pages and folders with extra
navigation can most of what I'm going to propose as a replacement.

I'm going to propose 4 things which may not be popular but please read on
and see my reasoning
They are:
- changesets or multi-document workflow
- table of contents, or ordered documentation or booklike documentation
- global editing
- get rid of document owners


Perhaps Plone needs the concept of changesets? Iterate could be extended to
link more than one draft version. Then if there was a need for a review
process, it could be done by workflowing the changeset object which links
all the changes of that objects together so that all the changes can be
reviewed together.

Why?

I'm sure there's a proper documentation turn for it but what do you call it
when the documentation is connected to each other in a structure more like a
big book? With a big table of contents.

Kind of like PHC tutorials but much much bigger. Like a PHC tutorial that's
written by many people??

The reason I think this might help is that
a) if everything has a place then it becomes more obvious when there is
duplication. If that table of contents is the main index people to use to
find things then people might try to improve whats there rather than add
alternate versions.
b) it gives people a place to start in understanding Plone. A start and an
end.
c) when people do write changes then reviewing it with regard to it every
thing else in the same section might lead to them discovering more things
that need updating.


I've just realized it would also need open editing, at least for anyone who
wants to make a change. Ie if someone could make a change then they could
change anything, not just one document.
If someone wanted to make a change that affected the documentation in many
places, lets say for instance updating official documentation to reflect the
adoption of dexterity. That would mean that person would need open editing
across all parts of the manual. And the workflow would have to support a
changeset so that many parts of the larger document at once could be
reviewed at once.
This is analogous to how it works in an open source code base. Everyone in a
large group has equal access to change anything they need to make something
work. It's done in a branch until it's reviewed. Then it goes into a
release.

I think this also means letting go of "owners" of documents. Owners mean
people feel they can't go in and change someone elses documents without
permission. I realise that highlighting ownership of documents, including
putting the pictures of the authors, is seen as a way to reward those who
contribute. And it does do that. But it also has this other negative affect
of meaning only that no one else is likely (or currently even able) to edit
another authors work.


Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:+61421477460 ~ MSN:dj...@ho... ~ Y!+Skype:dylan_jay ~ ICQ:520341 

> -----Original Message-----
> From: Steve McMahon [mailto:st...@dc...]
> Sent: Sunday, 16 November 2008 9:19 AM
> To: Plone Docs List
> Subject: [Plone-docs] Brainstorming next PHC
> 
> When PHC was first designed, the Plone community had a new, shiny tool
> -- the easy ability to develop new content types -- and PHC's response
> to the need for different types of documentation was to provide
> different content types for each. The types were fetishized into
> seeming to have some information architecture significance, and so PHC
> presented documentation by content type (how-to, tutorial, manual).
> 
> By the time of the Google DocComm sprint (an eternity ago -- about a
> year-and-a-half), we'd realized this wasn't working very well for a
> large document-base and a group of us engineered a clunky fix to
> present the documentation by topic rather than content type. A
> particular clunkiness was that the documents were still hierarchically
> organized by content types, meaning you had to find your way to the
> "how-to" folder to create a how-to.
> 
> Now, we're in the Plone 3 era, and the shiny, new toy is reducing
> content-type proliferation, and making fewer types more polymorphous.
> This offers possibilities for a much less clunky PHC, and is the idea
> Limi's been mentioning for some time.
> 
> So, I'd like to see some work on re-architecting PHC to emphasize
> team-management and information architecture rather than content type.
> (We've also absolutely have to have a clean migration path from
> existing PHCs.)
> 
> What I'd like to know is:
> 
> * do folks see problems in advance?
> 
> * who's enthusiastic enough to work on this?
> 
> * who would be enthusiastic enough to help organize a sprint, possibly
> early in the new year, probably west coast US? I suspect that this is
> a project that could be substantially realized in a single,
> well-planned sprint.
> 
> Steve
> 
> --
> 
> Steve McMahon
> Reid-McMahon, LLC
> st...@re...
> st...@dc...
> 
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
> world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> Plo...@li...
> https://lists.sourceforge.net/lists/listinfo/plone-docs