How to get answers in a public forum

[orbeckst]

When I am asking a question in a public forum such as the MDAnalysis Discussions and Discord, I am hoping that someone will take the time to read my question, understand what my problem is, think of a solution (which has eluded me so far), and write it down in a way that I can understand it.

That's actually a lot of work for someone to do, especially given that most people only have very limited amounts of time available to help others. For MDAnalysis, which is largely an open source project running with volunteer contributions or very focused grant funding for specific projects, nobody gets paid for answering questions. Therefore, if I want to have any chance to get a solution, I want to make it as easy and as rewarding as possible for others to help me.

Making it easy

• Write a title that summarizes the problem.
• State what you want to achieve.
• State what you did (show code, output, graphs!).
• Say explicitly why your approach is not working. Don't have your readers interpret your output. "I expected to see X but instead I got Y as shown ...".

Essentially this boils down to making an effort to solve your problem and while doing so, being able to define the problem as clearly as possible. The better defined your problem is, the more likely it is that someone will be able to give an answer.

Avoid open-ended questions if you want useful answers.

Making it rewarding

It actually feels great 🎉 to help someone else by using one's own understanding of a subject! It also feels very good to interact with other people.

So my advice: reinforce these rewarding feelings by doing the following:

• If you ask a question and someone else asks for more details then work hard to provide exactly what they asked for — they need this information to exclude certain failure cases or to test a hypothesis for what could be the cause of the problem.

• Be patient if you are asked multiple times to provide more and different information — they are essentially teaching you how to debug your problem.

• If your problem gets solved then add a comment that says what solved your problem! This does two very important things:

  1. Other readers of the discussion learn how to solve the problem.
  2. Each person who helped solve the problem now knows that they made a difference — and that feels good!

  Stating if and how the problem was solved is the best way to say "thank you" for the help that you received — this is much, much, much more important than leaving a comment "Thank you for your help!".

  If the forum has a way to mark a question as answered then please do so, too. It helps other readers (and probably also large language models/AI) to find solutions to problems.

Further reading

A lot has been written about this subject: I highly recommend reading the following:

• Alan Grossfield. How to be a good member of a scientific software community. Living Journal of Computational Molecular Science, 3(1):1473, Jan. 2022. doi: 10.33011/livecoms.3.1.1473. (open access, anyone can read this article — please do!!!)
• Simon Tatham, How to Report Bugs Effectively
• Eric S. Raymond, Rick Moen How To Ask Questions The Smart Way

[hmacdope]

Pinning to top of general

[RMeli]

I pinned it on top of discussions and added a link in #4355

[orbeckst]

It also helps when your posts are nicely formatted.

General tips

• Learn GitHub markdown!
• Use bold and emphasis to highlight key phrases.
• Use headings (## level 2, ### level 3) if it helps with readability.

Code blocks

Code blocks such as

import MDAnalysis as mda
u = mda.Universe("topology.tpr", "traj.xtc")
for ts in u.trajectory:
   print(ts.frame)

are produced with fenced code blocks and syntax highlighting is enabled with the python keyword. The code block above looks like the following when typed:

```python
import MDAnalysis as mda
u = mda.Universe("topology.tpr", "traj.xtc")
for ts in u.trajectory:
   print(ts.frame)
```

Mathematical expressions

If you want to typeset math on GitHub, then you can use MathJax, which implements a subset of LaTeX, as described in Writing Mathematical Expressions.

You use $ delimiters for inline expressions, e.g., $e^{\pi i} + 1 = 0$ was produced by $e^{\pi i} + 1 = 0$.

Often, displayed equations look better

$$\mathrm{RMSD}(t) = \min_{\mathsf{R}, \mathbf{t}} \sqrt{\frac{1}{N} \sum_{i=1}^N \left(\left(\mathsf{R} \mathbf{x}_i(t) + \mathbf{t}\right) - \mathbf{x}_i^\mathrm{ref}\right)^2}$$

and they can be produced with text such as

```math
\mathrm{RMSD}(t) = \min_{\mathsf{R}, \mathbf{t}} \sqrt{\frac{1}{N} \sum_{i=1}^N \left(\left(\mathsf{R} \mathbf{x}_i(t) + \mathbf{t}\right) - \mathbf{x}_i^\mathrm{ref}\right)^2}
```