Brainstorming next PHC

11 messages

Steve McMahon () Brainstorming next PHC

Reply Threaded

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
[hidden email]
[hidden email]

-------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

JoAnna Springsteen () Re: Brainstorming next PHC

Reply Threaded

I'm working on a proposal that could easily work with these ideas. I
was planning to post it to the wiki with the other doc reorg ideas.

As for sprints, I've talked with a few potential sponsers and might
have a sponsor and location lined up as soon as December. No definites
just yet but I'm working on it. If anyone has a location they want to
offer up for free that's a huge deciding factor. I'd say east coast
though so our friends from Europe can more easily attend.
J.

Sent from my iPhone

On Nov 15, 2008, at 4:18 PM, "Steve McMahon" <[hidden email]> wrote:

> 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
> [hidden email]
> [hidden email]
>
> ---
> ----------------------------------------------------------------------
> 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
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

-------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Graham Perrin () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

Steve McMahon wrote:

* do folks see problems in advance?

None foreseen by me.

(We've also absolutely have to have a clean migration path from existing PHCs.)

(That should absolutely wipe out *most* problems that a person might envisage.)

* 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.

I could happily participate remotely from the UK.

This assumes (without directing what might happen) that the sprint can be open to remote participation (†) without reducing effectiveness.

… seeming to have some information architecture significance, and so PHC presented documentation by … how-to, tutorial, manual …

Whenever I find myself drafting too much into an FAQ, the PHC is a perfect reminder that … I'm writing too much ;) and so I create a how-to. For this and other reasons I do have a fondness for the current arrangement of PHC (but will be pleased to see fewer content types across extended Plone sites in general).

… wasn't working very well for a large document-base …

(I'll be pleased to learn more about the workings/failings, I'll do so away from this thread.)

… hierarchically … to the "how-to" folder to create a how-to.

Defocusing from the content types issue, I actually _like_ the direction to a folder … at least, at time of creation of an object. I guess that the current PHC hierarchy is of less immediate value to an end user who is simply browsing. In any case I'm open to suggestions/sprinting.

I'd like to see some work on re-architecting PHC to emphasize team-management and information architecture rather than content type.

If PHC is not or was not working very well for a _large_ document base, then let's put on the agenda for a sprint, at least:

* fitness of new/future PHC for management where teams are _large_

— the larger a team, the greater the likelihood that an _architecture_ of any sort (not just documentation) will please all in the crowd

* flexibility.

(By fairly addressing/predicting such issues during a sprint, we may minimise requirements for future sprints on the same topic.)

Steve and co, I very much like the idea.

Thanks!
Graham

---

† FWIW I reviewed a number of collaborative real time editors in September, I'll share the relevant URL in due course.

Graham Perrin () Re: Brainstorming next PHC

Reply Threaded

Graham Perrin wrote:

— the larger a team, the greater the likelihood that an _architecture_ of any sort (not just documentation) will please all in the crowd

With apologies for word blindness, I actually meant:

— the larger a team, the greater the likelihood that an _architecture_ of any sort (not just documentation) will please _not_ everyone in the crowd

or

— … can _not_ please all in the crowd.

----

PS to Steve and others who pick up my pieces in Trac: for a sprint such as this I should almost certainly take myself out of bug-finding mode, I imagine that finding fault is not conducive during creative sessions! Most interest in UI and in immediate usability.

Dylan Jay-4 () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

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:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341

> -----Original Message-----
> From: Steve McMahon [mailto:[hidden email]]
> 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
> [hidden email]
> [hidden email]
>
> -------------------------------------------------------------------------
> 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
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

Anne Bowtell () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

Steve McMahon wrote:

>
> * do folks see problems in advance?

Please could we decide on the information architecture and approach first.

Anne

-------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Matthew Wilkes () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

On 15 Nov 2008, at 22:18, Steve McMahon wrote:

> * do folks see problems in advance?

That depends on what we want to do. Having a document available for
multiple plone versions with minor differences could be tough, for
example.

> * who's enthusiastic enough to work on this?

Yo.

> * 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.

If the sprint was during university holidays I'd be able to remote, if
it wasn't I'd be able to contribute. I wouldn't be able to afford to
attend in person, though.

Matt

-------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Roberto Allende () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Anne Bowtell

Anne Bowtell escribió:
>
> Steve McMahon wrote:
>
>> * do folks see problems in advance?
>
> Please could we decide on the information architecture and approach first.
>
> Anne
>

I'm not very involved with documentation and probably i won't say
anything new... but just in case:

Once a while, i saw in a competitor website, they had organized the
documentation in topics according the stage or kind of job someone is
needing to do, for example:

* Adoption
* Installation
* Look and feel customization
* Adding new content types
* Middleware development

Right now we've something like that, but we list subtopics. And i
believe it's far clear just show the main topics and click them to get
the subtopics. Probably this could help to organize the information too,
if you're not doing already.

Kind Regards
r.

--
http://robertoallende.com

-------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

vedaw () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

I'm a little slow to reply here, but yes, count me in.

I'm not really in a position to organize a sprint right now, but if I had
some help, I could assist. Are we thinking California again, or another
location?

On 11/15/08 2:18 PM, "Steve McMahon" <[hidden email]> wrote:

Dylan Jay-4 () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Steve McMahon

Sorry I haven't replied to this sooner.

I 100% think that some of the problems with documentation are a direct
result of the workflow and workings of the PHC content types.

So +1 for changing them. That is why I started kaizenplone.org in the first
place (the original was started as a PHC howto believe it or not, but
because its not possible to share edit rights with any user I abandoned it).

Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:+61421477460 ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341

Graham Perrin () Re: Brainstorming next PHC

Reply Threaded

In reply to this post by Graham Perrin

Graham Perrin wrote:

I could happily participate remotely from the UK.

This assumes (without directing what might happen) that the sprint can be open to remote participation without reducing effectiveness. … I reviewed a number of collaborative real time editors in September, I'll share the relevant URL in due course.

I don't whether the sprint will benefit from software of this nature (somehow I doubt it) but here, as promised, is a collection of notes on concurrent editing software:

<http://groups.diigo.com/collaboration/bookmark/tag/concurrent+editor>

Regards
Graham