Howtoask

From Yade

Revision as of 09:57, 29 August 2018 by Jduriez (talk | contribs) (Please, no external links!)

How to ask questions as a user of Yade (or any other computer code)

If you are directed to this page, it could mean that you asked a question to one of our mailing lists in an inappropriate way. Please check the tips below and try to improve your question.

If you spontaneously decided to read this page: congratulations! We hope it will be useful.

Before asking any question, you may consider searching through the mailing list. Probably someone faced a similar problem before and got a solution. The most convenient way to search among previous questions is probably typing some keywords together with "site:https://answers.launchpad.net/yade" in your favourite search engine.

If your search is not successful:

  1. Please don't send questions directly by emails to yade-users. Instead, use the "Answer" tool provided by launchpad, which helps sorting questions and answers. Once, a question is asked there, you will still receive answers in your mailbox, and you can "reply" to them with your email client. When the question is answered please mark it as such in the launchpad interface. If you want to show appreciation towards a particular decisive answer, you may click the button "This solved my question" (the corresponding user will be rewarded with Launchpad karma!)
  2. try to describe your problem in a concise and accurate way. Some context can be useful sometimes (I'm trying to achieve this or that, I'm beginner/advanced/expert in Python, etc.) but in most cases it does not help a lot, it should be short.
  3. Together with problem statement, send also a script which will let others reproduce your problem. Do your best to send it as a MWE (Minimal Working Example™). The MWE should actually be the smallest script possible showing the same problem you faced probably in a much longer script, initially. It must be:
    1. minimal = short. It is difficult to find mistakes in long pieces of code and it is usually much more annoying. Any post-processing command should for instance be banned.
    2. working = before sending, test it to be sure it is working (it has no syntax errors etc.).
  4. Together with the above information, send also the version of Yade you are using. If your question is linked to compilation issues, tell which operating system you use and show the logs of cmake and/or make.
  5. Do not merge different questions in one single post, even if - in your mind - they are connected to one single project. If your question received satisfying answer(s), mark it answered immediately. Do not use the same thread to jump to another question, open a new question instead.
  6. Train your empathy on this example, a fictious but archetypal question which typically appears without further info. What is the probability for programming gurus to understand the problem in your opinion?
    "Hello, I was trying to modelize a problem but python was returning an error. So, I changed some engine but now yade crashes. Can you please help?"

Please, no external links!

Launchpad will not let files be attached to questions and answers. As a workaround many users tend to provide links to external repositories. However removing the need for external files is part of creating a good MWE, hence external links on Yade launchpad are declared poor practice and should be avoided.

  • External links mean the potential responder will need to click multiple times just to read the question, while he/she is possibly reading it offline (via emails) and on an arbitrary device (e.g. cell phone). This potential responder might then simply move to next question (some of them even systematically do so).
  • The persistence of external links over time is not guaranteed, it will make the archive incomplete.
  • External links are not properly crawled into by search engines

How to avoid external links:

  • Showing a script should be possible in launchpad, since the scripts are supposed to be short (see previous section on MWE).
  • If the input of one script is the output of another script, then both scripts should be merged into one. That is: avoid sending multiple scripts just like you avoid sending input files to a script. If needed, the method to save and reload in one single script is illustrated here.
  • Error logs (be it compilation or runtime error) can be long, sometimes, yet the relevant lines are not many. If the log is very long please identify the error which comes first and paste only that one (together with user's input command).
  • Input files with particle coordinates or input mesh are not needed, in most cases. They can be replaced by writing coordinates directly in the script or using makeCloud or similar functions. Most problems are not due to a specific number of particles or the specific shape of an imported geometry. Instead, they can be reproduced with just a few facets and a few spheres (or clumps or whatever is in a specific situation).

Although removing external links may need a bit more work before sending the question, this extra time spent by the person asking means less time lost by the person answering. This is just fair. Moreover, by doing so you may well understand the problem by yourself in many cases.