Effective mailing-list communication¶
Don’t “top-post”¶
Many mail readers show quotations of earlier mails as indented with
> characters. Put your replies after what you’re replying to. Why? Example:
> Because it messes up the order in which people normally read text.
>> Why is top-posting such a bad thing?
>>> Top-posting.
>>>> What is the most annoying thing in e-mail?
In other words, use interleaved and/or bottom-posting style. See also https://en.wikipedia.org/wiki/Posting_style.
Please don’t email your questions directly to ‘experts’¶
The so-called ‘experts’ need the answers to any questions to be in the public record as a resource to others having the same problem in the future. Make this easy on the ‘experts’ by posting to the list.
There are (hopefully) many people on these mailing lists that will have the answer to your question and you might be helping others who are having the same problem.
The best part is that someone who is awake may answer your question while you are asleep. If you converse with one person who is not online or not answering right away your answer may drag on for days. That’s assuming that that one person could have answered your question.
State your problem clearly.¶
Avoid confusion or ambiguity. What you write is what the person answering your question will be working with.
Explain what happened, let us know how you tried to resolve or fix the problem, so that we don’t have to ask if you tried something. Including what did not work will reduce the replies that repeat what you already tried. Be specific.
Try to phrase your question so someone will not have to ask:
What did it do instead of working?
What do you mean by working?
How do you know it is not working?
When did the problem start?
Can you reduce this to a portion of code that fails?
If you are not using a meta-project, or have added a module to a meta-project, please specify clearly in your email if you did such a thing. Obviously it is difficult to diagnose problems e.g. compiling code, when one doesn’t know what code is being compiled.
Isolate the problem.¶
The more you tell the list up front, the easier it is for the list to answer your questions.
The fewer lines involved with the problem the easier it is to answer. Don’t include a 200 line script if you can isolate the problem to a few lines and make a smaller example.
Some dreaded phrases: “I am having trouble with this”, “This doesn’t work”, “This gives me the wrong answer”, “IceTray doesn’t work”.
Please keep in mind that we are not mind-readers, so please post clear questions. Don’t make us ask Who, When, Why, How, How Much, or What does it do instead of work? If your question isn’t clear, responses will be delayed, and additional email traffic (which costs time) will be required to clarify the question.
State the problem plain and simple and then give additional information. Include (as appropriate): metaproject version, operating system and version, compiler version (if dealing with compiler errors) error messages (text only, no attachments), what was expected and what happened instead.
Be very specific when reporting error messages.¶
Don’t say “I get an error when I do this.” Post the exact text of the error message, after that is what one would use to search Google. Exactly what did you do to get the error? Was it generated by root, icetray, or python? Do you know which module generated it? Include the steering file that that caused the problem.
If you know the answer to someone else’s question, answer it¶
This is a peer-to-peer group, not users-to-‘experts’. If you think you know the answer, but aren’t sure, start your reply with ‘I think …’ Try to avoid giving an incorrect answer in a definitive manner.
Try it out.¶
Before posting a question asking “Will this work?” or “Can I do this?”, try to answer your own question first by testing/experimentation before posting. You may be smarter than you think.
Use an illustrative subject line.¶
Don’t put in a subject line like “HELP ME!” or “icetray question.” Instead, say something like “StreamError writing TWRMCHitSeriesMap”.
Don’t use meaningless words in the Subject
- emergency
unless shutting down means losing data it probably isn’t.
- Help
everybody with a question is looking for help
- Question
almost all threads begin with a question so the word adds nothing
- urgent
everybody with a question is looking for help
Use the subject line to properly identify the problem. Single words are not adequate. Misleading subject lines make it difficult to locate your question again when we can answer it. It is also frustrating to answer a question only to see that part of the description was contained only in the subject line. So make sure that the subject line matches the question.
Many people choose what they read based on the titles of the mails, so be precise if you want more eyeballs on the problems you post.
Missing or misleading error messages are bugs!¶
Bad error messages account for countless hours of lost time as users attempt to fix something that isn’t actually broken. If you find a module that encounters an error, but gives you no error message or a misleading one, report it. Include what the problem actually was (and what the software claimed that it was, if it claimed anything).
If you’ve struggled with a useless/vague error message, don’t let the problem state slip away¶
If you have encountered a problem and got a bad/incorrect/useless error message, the most important part of fixing it is getting some kind of a check in so that the error message is correct in the future. This benefits everyone and contributes significantly to the long-term stabilization/reliability of the code.
For this reason, it can be frustrating to hear so “It works now” or “Jimmy helped me fix it” without having isolated the problem to the point where it can be accurately reported in the future. Try to note exactly what was incorrectly detected/reported so that a fix (and hopefully a test) can go in.
If you have a compile / build problem, include verbose make output¶
If your problem appears to be in the build system, be sure to include
the output of your build with verbosity on, by adding
VERBOSE=1 to the command line:
% make VERBOSE=1 doxygen
/usr/local/bin/cmake -H/home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/src -B/home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/build --check-build-system CMakeFiles/Makefile.cmake 0
make -f CMakeFiles/Makefile2 doxygen
make[1]: Entering directory `/home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/build'
/usr/local/bin/cmake -H/home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/src -B/home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/build --check-build-system CMakeFiles/Makefile.cmake 0
/usr/local/bin/cmake -E cmake_progress_start /home/troy/Icecube/meta-projects/offline-software/trunk/clean-docs/build/CMakeFiles 4
make -f CMakeFiles/Makefile2 CMakeFiles/doxygen.dir/all
[ etc ]
This way the details of the commands that are executed are available for diagnosis. There may be a tremendous amount of output; it might make sense to include only the bits that are related to the failure.
State clearly what software you are using¶
Diagnosing problems can be very difficult if people are unable to reproduce them. Therefore, it is important to state what versions of projects / meta-projects are causing the problem. The problem might already have been fixed in a newer version or on trunk.
Especially, if you include further projects in a meta-project release you might be on your own. Meta-project maintainers invest a lot of time to make sure that meta-project releases and the trunk are working. Extra projects may require dependencies that are not satisfied in a given meta-project release.
