2022-06-25 Ver. 0.1 [draft]
Table of Contents
- Before you ask questions
- When you ask a question
- Content of the question
- Logs and configuration files
- The times must match
- Ask one question at once
- Report the result
- Further readings
At first, consider using paid support if either of the following apply:
-
The deadline for resolving the problem you are facing is imminent and can never be extended.
-
You do not want to learn about Sympa and do not intend to be able to solve the problem on your own in the future.
Technical mailing lists are not the "support center" but a kind of "mutual aid society". No one is obligated to solve your problem. If you want someone to fulfill such an obligation, please hire such a persons with your money. There are some persons on this mailing list from organizations that provide such services for the users of Sympa, so ask them.
If you decide not to use paid support, then read on.
Your question should include the following information:
- Title (or subject line, if you use mailing list to ask question)
Provide a general summary of the issue.
- Version
Versions of Sympa and related software (RDBMS, MTA, HTTP server, ...).
- Installation method
How you installed Sympa: deb, rpm, ports, ... or source package.
- Expected behavior
Tell us what should happen.
- Actual behavior
Tell us what happens instead of the expected behavior.
To explain the exactly actual behavior, it is helpful to attach messages that were output to the console and/or system log (see also "Logs and configuration files" below).
- Steps to reproduce
Actual steps that can reproduce the actual behavior. "I opened URL 'aaa', clicked 'bbb' button, ..." and so on.
In addition to such instructions, you should also attach the contents of the configuration files as necessity, so that the persons reading your question can reproduce the problem on their own (see also "Logs and configuration files" below).
- Additional information
Anything else you would like to add other than the above.
You may also attach configuration files, logs and so on. Rather they are MUST if you are asking for a solution to some problem.
NOTE: You should not include sensitive information!
- Logs
In the case of Sympa, syslog output is usually sufficient for logging content (rarely, the stderr files in the tmp spool are also useful).
However, if you are asked to see other logs, provide them additionally.
- Console output
If you are using command line utility, output in console are also useful.
Console output should be copied and pasted in its entirety. The one line or phrase that caught your eye may not necessarily be the most essential information.
- Configuration files
What is needed varies.
-
First, among the Sympa configuration files, sympa.conf (and robot.conf if any) is MUST.
-
If you are having problems with a particular list, you will also need the list's config file.
-
If the problem is related to a specific feature, you will also need those config files. For example: message_footer file for adding message footers.
-
You may also need the MTA configuration file(s) if you are having problems receiving or delivering mail; the HTTP server configuration files related to the Web UI or SOAP.
On these software, sometimes the configuration files may be in multiple pieces, but if you are not sure which is essential, provide all files that have ever been edited since the software was installed.
However, if you don't know what are essential, there is no need to attach everything from the beginning. If you are asked to show the other files, provide them additionally.
It is important that the times of the above information match. In other words:
-
The log must include the time period from the beginning to the end of the procedure described in "Steps to reproduce". And during this period, the events described in "Actual behavior" should have occurred.
-
The configuration file must be the actual content during the above period.
Information that doesn't match, i.e. has no relevance to the events, is useless. It is easy to lose track of what happened during what settings, if you keep trying to modify the configuration files over and over again. Be careful.
You'd be better to ask a question at once. If you are encountering more than one problem, at first ask only one question that seem the most urgent.
Once you have asked a question and received an answer, at last whether the problem is resolved or not, post the results.
As I wrote at beginning, technical mailing lists are not the "support center" but a kind of "mutual aid society". The problem you encountered and the experience of solving it may also be useful to someone else in the future.
That's why someone answered your question.
- Yuki, H. (2001). "Pattern language when asking questions on the technical mailing list". [japanese] https://www.hyuki.com/writing/techask.html
Machine translation in french:
https://www-hyuki-com.translate.goog/writing/techask.html?_x_tr_sl=ja&_x_tr_tl=fr
- Raymond, E. S. (2014). "How to ask questions the smart way". [english and others] http://www.catb.org/~esr/faqs/smart-questions.html
2022-06-25 Initial revision posted to sympa-users list