From: Dylan J. <dy...@dy...> - 2008-11-16 14:49:26
|
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 |