Skip to main content

Home/ Plone distributed documentation/ Group items tagged advice

Rss Feed Group items tagged

Graham Perrin

On Plone documentation - Martin Aspeli - 1 views

  • I think it's a mistake to try and solve all the problems with "Plone documentation" in the same way
    • Graham Perrin
       
      +1
  • rely more on technology
  • What is current good practice?
    • Graham Perrin
       
      My initial reaction to this: get started | essential actions | refinements and current best practice …
  • ...20 more annotations...
  • a corpus small enough that it can be effectively reviewed
  • highlighted and easy to find
  • this is where they should be stumbling
    • Graham Perrin
       
      Can we elaborate on this point?
  • Barriers to entry should be low
  • version the document pertains to
    • Graham Perrin
       
      +1
    • Graham Perrin
       
      Re http://dev.plone.org/plone/ticket/7831 some simple triggers might draw attention to documentation that becomes outdated (or at least deserves review) at product update time.
  • concerned about how easy it is to add an article
  • highlight the "good" bits of documentation
  • reviewed at least each time we make a new Plone release
  • What's the right way to configure caching?
    • Graham Perrin
       
      Advice may be diverse.
  • If someone wants to contribute documentation, by all means let them!
  • allow comments
  • ratings of the type "was this helpful to you"
    • Graham Perrin
       
      I do often rate things (positively more often than negatively). However: I rarely observe other people's ratings.
  • Open the flood-gates
  • group documentation by audience, rather than by type
    • Graham Perrin
       
      I'm never wholly convinced about audience-based documentation.
    • Graham Perrin
       
      Can we group documentation by layer - through the Plone (TTP), Zope management interface (ZMI), file system et cetera?
  • Accept that how-to documentation won't be perfect
  • Add ratings
  • improve commenting
  • this is out of date
    • Graham Perrin
       
      Maybe "This is valid for version n.n of product x" plus "For more recent advice please visit …".
  • We should allow people to make requests for new documentation, and expose the wish list in a way that lets people vote for their favourite requests
    • Graham Perrin
       
      First improvements to a document might be: (1) a link to Trac, so that any documentation-related issue can be tracked; and (2) an in-document summary of relative tickets.
  • We have a Trac
Graham Perrin

Plone 3.1.1 released! - Plone CMS: Open Source Content Management - 0 views

  • If you're running older Plone 2.x sites and are unable to upgrade — make sure to follow some simple rules
Graham Perrin

Of babies and bathwater (or: Why I love the Zope Component Architecture) - Martin Aspeli - 0 views

  • Of babies and bathwater (or: Why I love the Zope Component Architecture)
  • Martin Aspeli
  • Dec 01, 2009
  • ...17 more annotations...
  • In defence of one of the great Python frameworks of the past decade
  • ZCA rocks. It's an incredibly advanced and powerful way to build software
  • ZCA adds complexity. It demands that you swallow its core concepts up front (interfaces, adapters, utilities, events) and get to know them pretty well
  • people can do crazy things, usually doing as much harm as good
  • elegant frameworks like BFG or Pylons
  • That doesn't mean the ZCA is right for all situations
  • learning to use the ZCA effectively is a bit like learning a new programming language on top of Python. You need to "get" those concepts
  • For the ZCA itself, there is clearly an opportunity right now to evolve
  • My personal wish-list
  • advice for projects, such as Plone, that use the ZCA for extensibility and inversion-of-control
  • Don't let the ZCA be the first API that people see
  • don't assume everyone has yet reached ZCA mastery
  • ZCA as a building block
  • BFG does this very well
    • Graham Perrin
  • We're trying to do something similar with Dexterity and the ecosystem of tools around it
  • The same will hopefully be true for other technologies as we move towards Plone 5
  • improved integrator learning curve
1 - 3 of 3
Showing 20 items per page