Asking for help: guidelines and examples

Newcomers: a guide to your first post

As you prepare to post your first question, please consider the sections below. A well-phrased question increases the likelihood of a timely answer.

When in doubt: post to the general questions (plone-users) area. If you're new to Plone community, you might like to offer a brief introduction.

If you prefer Internet relay chat (IRC), join the #plone channel on freenode. The support area of this site offers a convenient web interface. You may see much technical discussion, but the channel is not for developers alone: we welcome questions from all people who show consideration for these guidelines.

Noise

For multiple lines of text, or for long lines:

Beware: items in paste.plone.org are not persistent! Occasionally, its bin is emptied.

• pastie.org is usually preferred

• paste bins elsewhere, such as pastebin.ca, may offer greater or user-defined persistence
• there is no bot-link between paste bin and channel: you should announce to the channel the URL of your paste.

Next steps

People who have the time and inclination may:

• ask you to provide additional information
• refer you to a more appropriate group or area.

An apparent silence may indicate that you phrased a question in a way that was not easy to answer. Solving problems is a skill set with fairly well-established parameters. As with any skill set, you will improve through practice; and many of the skills that you gain in the Plone community will be transferable!

Gaining answers: the value of good reporting

A most helpful exercise: write a semi-formal error report. Discipline in analyzing a problem will increase the likelihood of you gaining a solution or explanation whilst you write. If your writing does not lead to a new understanding, then your report should efficiently provide to other readers a good understanding of your situation.

A good report covers five key areas

1. The big picture.
   • An opening sentence should state the general problem that you wish to solve.
   • This orientation helps others to see whether your attempted solution is in the right ballpark.
2. A snapshot of your environment.
   • For Plone and for other relevant products: provide version numbers.
   • If additional information is required, we'll ask for it.
3. Steps to reproduce the issue.
   • A numbered list should allow someone else to reconstruct the environment then reproduce the error.
   • Before concluding that an error is not reproducible: try really hard.
4. The expected result.
   • A brief statement of your expectation will help to highlight any variation.
5. The actual result.
   • Specific is terrific!
   • If your error produces a traceback or other error message, provide this information in a legible form.

Depending on the difficulty of the problem — and your problem-solving skills — it may take you more than a few minutes to write your first error report. With practice, everyone improves. As you build relationships with the Plone community, formal error/problem reports should become less necessary: you will find in us a readiness to debug with you conversationally.

If you can not install a product, please provide the error message. Although there exist hundreds of add-on products for Plone, one good error message is often enough for troubleshooting. Without the detail of an error, it may be difficult or impossible to help.

Responses from the community

Sometimes: instead of asking questions that go deeper into the specific error, we will ask questions a frame or two up from the immediate symptoms. Please be prepared to think outside the box.

Other times: the error may represent a limitation of the software. By chance or by design, a current version of Plone may not suit your use case. If you find yourself in this sometimes frustrating situation, your options include:

• Leave.#php is right next door. Tell 'em limi sent ya. ;^)
• Stay and Bitch. I mean, we can't really stop you.
• Stay and Mooch. The ranks of the Plone welfare state grow every day.
• Get involved. Write code or docs, or hire someone to do so — we place equal value on both approaches.

Plone is a community. Ultimately people talk with each other in the chat room, in the fora and on the lists because they have worked together and drunk beers together for years. We welcome newcomers!

Our preference is for you to be involved!

To demonstrate good faith, a great way to start is:

• following the guidelines offered on this page.

Special considerations when addressing a forum/list

Bear in mind, most people will read a message only if it appears to be intelligent, and if it clearly relates to their areas of expertise. As your line is your sales pitch, so you should make your subject line specific and likely to please.

A poor subject line

GET METHOD!! URGENT HELP!!!!

• offering no useful detail whilst SHOUTING with !!repeated exclamations!!!! will gain least attention
• at busy times, some readers may be angered by the noise.

A better subject line

Passing GET variables to FormController scripts returns FooError

• a short but expressive statement that will be recognisable to anyone with a knowledge of such scripts/errors
• thoughtful use of keywords/key expressions in a subject line will lead to high ranking and high relevancy in search results, and may encourage easy reading by concerned individuals/groups

Changing a subject line within a thread

A focused subject line can be very useful, especially to future readers of topics that are long, multi-threaded or complicated.

• Particularly in environments such as Plone, where mutiple/diverse technologies and add-on products are involved, a problem topic that originates with one subject may conclude (following troubleshooting and explanation) with a subject that bears little or no relationship to the original.

A well-designed mail/NNTP reader will present a thread in its entirety.

Beware! Less well-designed reader software may effectively break or lose some types of thread/topic. (There are known problems with Google Mail beta.) The appearance of breakage be annoying to the reader, so please exercise discretion when changing a subject line.

• Tip: using the Plone support forum web interface to post should guarantee a lasting context to your message. A Nabble reference is included in all such posts (example) and wherever the reference appears, the reader need not be lost.

Special considerations when using IRC

The freenode service, used by Plone and many other communities, offers excellent guidelines. Whilst using the Plone channel in freenode, please help yourself — and the community — by following the guidelines.

Please be specific.

Don't ask meta-questions. You need not request permission to ask a question before asking your question.

Some people review channel activity only occasionally, and answer questions when they find the time to do so — listeners are not obliged to help you. The likelihood of gaining assistance is high, but your question must be well-expressed.

Be patient!

Keep your lines reasonably short

• Semi-technically, according to most recent advice in irc://irc.freenode.net/#freenode: IRC is specified to handle 512 characters maximum total for the whole command, which has to have the :, the nick!user@host, several spaces, another colon, and the command, the destination channel/nick, and a \r\n at the end

in IRC: any line greater than 255 or 300 characters may be considered excessive

• informally: other users of IRC recommend fewer characters per line
• in any case: for masses of text, or for multiple lines, consider using a paste bin.

A poor line

"Anyone here using product XYZ? Anyone here have problems installing XYZ?"

A line that is more likely to gain attention and a positive response

""Hi, I'm using product XYZ, I have a problem with the feature that is supposed to do ABC — I get error BlahBlahError — what might be wrong?"

Credits

• This how-to originated as an informal, user-friendly alternative to Eric Raymond's How to Ask Questions the Smart Way. ESR's doc is long and offensive, though once you realize that ESR is your crusty old merchant-marine uncle it can be fun and helpful.
• The error report format is adapted from Joel Spolsky's comments on bug tracking, e.g., in Joel on Software.
• A review of this how-to is timely: we read this how-to (originated: 2004) alongside nearby asking-for-help (originated: 2007) with a view to merging the two, and maybe having a separate how-to that is tailored for error/problem situations.