youtube-logo 34xtwitter-1-logo 34xgithub-logo 34x

Here are instructions and guidelines for good communication. They provide hints and advice on how to avoid pitfalls and embarrassment. Note that there are many people on the mailing lists and forum 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.

Which mailing list and forum to subscribe to?

There are several mailing lists in which you can discuss topics and ask for help. However, before posting to a list or forum you should ask yourself if you are addressing the right one. Please check first which mailing list and forum would be most likely to cover your specific question.

 Go directly to the community mailing list and subscribe.

Use a good writing style

  • Make clear that you checked 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).
  • Do not add long source code segments (XML, Java, Javascript, ...) directly into the messages, especially not as HTML formatted text, but use services such as Pastebin, GitHub Gist, Pastie and the many alternatives.
  • Avoid binary attachments like images, etc.
  • Always respond to the list rather than just the poster. The discussion of your problem may help others later on who find it in the archive
  • Do not mess up threads! Compose a new message for a new question.

Writing your post

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 and (for discussions since 2010) forums. 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.

Final words

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.


Posters should be aware that the 52°North's lists are public discussion lists and anything you post will be archived and accessible via several websites for many years.

Affiliations

The 52° North affiliations:

OGC logo

Cooperation Partners

The 52°North principal cooperation partners

IfGI Logo con terra logo
esri Logo ITC logo