Plone troubleshooting
Reading the 'what's annoying about this list' thread on Plone-Users today. It's not going out on a limb to assume most novices have felt exactly the same way as Marie... I know I have, more than once.
I also know a thread like this one appears on the list every few months, and that in talking to other developers, especially ones working in small or one-person groups, this idea comes up a lot. It's not particular to Plone, either-- troubleshooting a problem in a large technology stack is sort of like trying to chase an unpaid invoice in a large company. You have to know not only where to look but also how to ask the right way.
And, while there are posted guidelines at plone.org about how to ask for help on the mailing list, here
http://plone.org/documentation/how-to/asking-for-help
and here
http://plone.org/documentation/how-to/ask-for-help
(as well as several blog posts on the topic)
these really are just the beginning. We could be better at pointing people in the right direction *before* they get to the list. I know, that's the point of most of the docs at plone.org, but there's a missing piece that could help newer integrators and developers get grounded in how to frame their doc search or help request.
Sometimes all you know is that your site is hosed and you don't know why. Or you're not sure whether your issue is with TAL or Python or Zope or Plone or CMF or AT or z3c or METAL or ZPT or .js or KSS or CSS or IE6 or Apache or zc.buildout or unsafe versions or Bad Code or Core or Add-on or Deliverance or .. or .. or ... or ... :)
How about a 'Troubleshooting' section at http://plone.org/support and/or http://plone.org/documentation that could put many of the existing doc pieces into a diagnostic setting?
Something like a flowchart that begins with "So, you've got a problem" and then walks novices through some basic steps to identify:
- the right level in the technology stack to address
- whether there's a specific mailing list or chatroom for that area
- whether they should contact the developer directly
- whether the problem is addressed at plone.org/documentation and how to search for possible answers
- whether and how they should go about contacting a consultant for bespoke troubleshooting work
- whether and how they should submit a request for documentation (do we use stubs? If not, are they under consideration? If not, I'd like to present an argument for their use...)
- whether and how to check the terminal for error messages
- whether and use and a couple cases for some of the debugging/introspection tools
- whether, how and in which tracker to file a bug report
A couple examples:
- Is there a list of the core & add-on product mailing lists anywhere?
- Is it clear whether an item submitted to the collective (collective.xxx.xxx) is supposed to maintain its own mailing list?
- If the product page lists a contact address and no mailing list, is the contact email assumed to be the primary support channel?
- Are mailing lists hosted at google-groups, etc searchable at http://plone.org/support/forums and do people know that?
- Is there a reason why http://plone.org/documentation/error is not linked from http://plone.org/support
