The mailing list for listmasters using Sympa

[IKEDA Soji <address@concealed>]

Hi abaidi,

I drafted the description.  Could you please try making a question
according to this? (I prefer to using GitHub Issue page than posting
to mailing list.  Because if you happened to post sensitive information,
it is much easier to hide it.)

Regards,
-- Soji


---------------------------------------------------------------------

How to ask the question to solve the problem about Sympa [draft]
================================================================

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

---------------------------------------------------------------------

Before you ask questions
------------------------

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.


When you ask a question
-----------------------

### Content of the question

Your question should include the following information:

  1. Title (or subject line, if you use mailing list to ask
     question)

     Provide a general summary of the issue.

  2. Version

     Versions of Sympa and related software (RDBMS, MTA, HTTP server,
     ...).

  3. Installation method

     How you installed Sympa: deb, rpm, ports, ... or source package.

  4. Expected behavior

     Tell us what should happen.

  5. 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).

  6. 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).

  7. Additional information

     Anything else you would like to add other than the above.


### Logs and configuration files

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.


### The times must match

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.


### Ask one question at once

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.


Report the result
-----------------

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.


Further readings
----------------

  - 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

---------------------------------------------------------------------