These guidelines provide hints and advice on how to avoid pitfalls and embarrassment. Note that there are many people on the mailing lists who help and support in their free time. Some are very direct and some may answer quite verbosely. Never take things personally and please be tolerant. Think about the answer twice when it remains unclear after a first reading.
52°North has a number of mailing lists in which you can discuss topics and ask for help. Before posting to a list, please check if you are addressing the right one to cover your specific question. Once you’ve figured that out, subscribe to the mailing list.
First check the documentation and the mailing list’s archive.
Provide all information concerning the problem:
- Relevant parts of an exception.
- Version number of used components (SOS 3.1.1 rather than SOS 3.1).
- Platform (Windows, Linux, MacOS X with their versions).
- Example requests and code snippets which are sufficient (not more, not less) to reproduce the problem.
- Give an informative subject line/title (`SOS error’ is not informative).
- Please send your postings in plain text, i.e. no HTML mails (see www.freeantispam.org email examples).
- Avoid binary attachments like images, etc.
- Always respond to the list rather than just the person who posts. The discussion of your problem may help others at a later date.
- Do not mess up threads! Compose a new message for a new question.
1. Get your facts straight
The most important section of a mailing list post is the problem description with a minimal reproducible example. The most important word in the previous sentence is reproducible, the second most important word is minimal. Many problems are already solved by trying to prepare such an example because you have to dig deep into the problem and understand it before asking for help.
The 52°North services provide test clients to send requests to the service. To make the problem reproducible to others, attach the XML requests and provide the URL of a service that is available to the public and shows the problem. If you have set up the service on your local machine, you should provide the URL to the developer. Mention in your posting if your server is not available to the public because it may be more difficult for others to help you then. Attach relevant configuration files you used to set up the service. In summary, try to provide the following information:
- The URL you send your requests (the “service endpoint”)
- The actual request (POST, GET)
- The log output in DEBUG mode
- Relevant configuration files and version information
2. Check further resources
Make sure that your question was not discussed already. Check mailing list archives. You can also find further documentation on the 52°North Wiki.
3. Avoid common mistakes in postings
- Missing or non-specific message subject
- Not consulting basic documentation before posting a question
- Not being more specific than `function xxx doesn’t work’
- Being overly specific and not stating your real goal
- Not including software version and operating system information in a question regarding unexpected behavior
- Not testing the validity of request documents (if XML) that cause an error with external tools, e.g. jEdit
- Posting screenshots of error messages instead of copy and pasting the text into the mail or using any pastebin service.
It is a skill to ask good questions. If at first you don’t get the answers that are useful to you, don’t get discouraged. A response that is concise and technically accurate may be just that, and not an intended putdown. If you feel insulted by some response to a post of yours, don’t make any hasty response in return — you’re as likely as not to regret it. Read Eric Raymond’s essay How To Ask Questions The Smart Way for more suggestions, and for insight into people’s behavior on technical mailing lists.
Please be aware that 52°North’s lists are public discussion lists and anything you post will be archived and accessible via several websites for many years.