Does it make sense for us to come up with a guideline along the line of How do I ask a good question? - Help Center - Stack Overflow?
For R users I’d like to suggest use reprex(..., session_info=TRUE) to make question/issue reproducible. Is there a similar thing for python users?
EDIT: reprex is an R pkg to parse R into markdown so the issue can be reproduced. See https://reprex.tidyverse.org/.
I think this is a great idea!
Great. I’ll take a stab on the initial draft then.
Looks like there’s a reprex port in python.
Here’s the draft. Comments? Suggestions?
We understand you are busy and need answer ASAP, and we’d love to help you. Here are some tips to improve your probability of getting an answer.
First and foremost, manners matter, use magic words! (here’s our code of conduct).
Please search on Discourse or google first. Don’t ignore relevant posts that do not directly answer your question. Share what your find in the post.
If you are reporting issues with a model or code, please don’t paste the entire program or output. Instead, try to reproduce the issue with an example that is as simple as possible. If the problem can only be reproduced with certain data, please attach that too. In other words, please make your example complete so that we can run it on our end.
Please follow category templates if provided. For code snippets and math expressions, use markdown (it takes only minutes to learn) and preview them before posting. Please stay away from plain texts, please absolutely stay away from screenshots.
In addition, detailed information about your working environment goes a long way. Depends on the question, there are tools to help you to achieve that.
For R users…
Please use reprex for nicely formatted code snippets. We recommend include session information as
reprex(..., session_info=TRUE)
For python users…
reprex has been ported to python. If possible please use reprexpy generated markdown with working environment information.
For c++ users…
If you are running into problems with c++ compilation or cmdstan, please attach information of platform, compiler, and relevant error messages.
For Stan users (remember why you are here?)
Most important of all, please provide the version of Stan and Stan interface you are using. This can be retrieved from cmdstanpy.show_versions() or cmdstanr::cmdstan_version(). If only “.csv” files are available, one can retrieve Stan version from the first a few lines:
grep "version" output.csv
The forum relies on volunteers with limited contribution window, so it helps if the question is phased like a one-minute pitch, with relevant details highlighted while noise minimized. For example,
Research rarely has straight answers, please be prepared for questions and feedback. We appreciate inspiring questions, but the broader the scope, the more iterations and longer the discussion. Be ready to engage, and manage your expectation. Also, please keep an open mind: it’s much more likely that a terse comment results from someone being busy rather than rude.
EDIT: updated per @spinkney & @Bob_Carpenter s comment.
EDIT: update per @syclik comment, thanks!
Bump. @Bob_Carpenter @rok_cesnovar @martinmodrak @mitzimorris @mike-lawrence @syclik @jsocolar @WardBrian @andrjohns
I’m thinking merging this guideline with the currently pinned greeting post after finalization.
I love it! Thanks for the effort!
Looks good to me. Some suggested changes.
asap → ASAP (it’s an acronym)
Maybe while saying that they should have a minimal working example, we should stress that it should be a complete minimal example. My usual follow-up says, “Thanks for giving us part of your program. It’d help immensely if you could also share the data and parameter declarations.”
I don’t know how you are searching, but I can’t find anything with Discourse search. I just search through Google. If you have search tips on Discourse, can you share them or point me to instructions?
I don’t think we should tell our users to be grateful for our help and we should follow our own politeness guidelines, so I’d change “Be polite and grateful” to “Please be polite”.
I think a 5-minute pitch is too much! It should be a 10 second pitch.
Maybe we should also tell people the forums are for questions about Stan, not general questions about R or stats.
I also don’t know how to suggest that really long programs are almost impossible to debug and the right approach is to build up to a large program from smaller working examples. So I almost always ask someone who sends a huge program what the largest version of the model is they got working and what went wrong with the extension.
Fixed / added “complete” for the MWE / Fixed.
I don’t find discourse search particularly terrible, so I just rephrased it as “search with Discourse or google”.
Let me meet you halfway at “one-minute pitch”.
I don’t have a good idea on that either. Maybe pointing to relevant “Bayesian workflow” sections like “modular constructions” & “starting at simple and complex models”, etc. ? On other hand I don’t want to stretch the post to long.
Thanks, Yi! I think it’s good.
There’s one bit of information that I think would be useful for debugging on our end. I know it states “please provide the version of Stan and Stan interface you are using” in the “Make it reproducible” section, but I’d really love it if there were cut-and-paste instructions here.
For “c++ users,” I’d de-emphasize “relevant” in “relevant error messages.” Unfortunately, until you’re really well versed in handling template metaprogramming compiler errors, it’s hard to know what’s relevant and what’s irrelevant and people will paste the wrong thing in.
Formatting… inside “For R users…” I think there might be a way to get the code block to be nested inside the Markdown block. Here’s a StackOverflow solution that might work: How to nest code within a list using Markdown - Meta Stack Exchange. ".
…you just have to leave a blank line and then indent by 8 spaces as a minimum.
This looks like it works…
some code here * bullet
```
some code here
```
Awesome! I like the ordering. I think we can expand on “Minimum working example” in other places so it’s clear. Once upon a time, I put a couple links to really well-written posts as examples. That might be useful if we find it. It doesn’t need to be here right away, though.
Thanks!
A common obstruction in Stan Forum posts is users who present their model in the jargon of their particular field, which makes it difficult and time consuming for others to offer any help. Beyond the software development practices in Make it reproducible I would strongly recommend an addition section like Make it general that advocates posters consider that most people who might be able to answer their question are probably not familiar with their particular field. Making examples as abstract as possible, or at least providing as much context for the inferential goals and idiosyncratic variable naming, as possible goes a long way to making questions accessible to potential responders.
As reprex is not a standard package its recommendation should be treated with care. Installing the tidyverse is not a trivial operation for many and it can seriously mess up local environments due to its poor encapsulation. I think that something as simple as “If you have the reprex package installed consider wrapping your session information with the call…”, etc.
With anxious users in mind let me note that some of the language here comes across as a bit condescending. There are many commands “use this, do this, etc” instead of recommendations “consider this, try this if possible” and phrases like “it takes only minutes to learn” are often off-putting for those who are not familiar with markdown.
I appreciate that many users don’t help themselves with the formulation of their questions, but I think it’s better to offer more guidance than orders to keep the Forum as welcoming as possible even if it means that poorly formulated questions aren’t removed entirely.