What should our FAQ contain?

Question

We've talked about here and there pieces of this, but what should go in our FAQ? What do you think needs to mentioned in our FAQ? Obviously, what is considered on-topic/off-topic, and quite possibly a number of items from this list. But, we should start making progress on this question.

(This is question number 2 of the 7 Essential Questions.)

---

Edit by J. M.: I have started editing the first entry of the main site's FAQ. Please give any suggestions/additions/feedback in this thread. Thanks.

---

Edit by R. M.: Since it's been a little more than a year, it's worth revisiting this and discuss if something needs to be added/removed/modified. The membership of the site has also grown in this time, so input from the newer users is also much appreciated.

Answer 1

–

When new visitors arrive to this site and post a question it's very often the case that the question looks like this one

Everyone knows what now usually happens: The question is rarely upvoted and it is heavily commented that question should contain a description what the OP has tried so far, maybe working, small sample code and all the things which are required for a good question (I missused Istvan a bit).

Here are 2 comments of this answer

When I now look at the first section of our FAQ then I think it's maybe not the best thing to start with because

1. about first paragraph: Most new visitors know that this is about Mathematica without reading the FAQ. The few that ask mathematicS questions seem not to care about the FAQ anyway. A sentence would be fine, but a whole paragraph?
2. about off-topic questions: We don't have so many questions about W|A. In fact, we delete/move more mathematics questions than having W|A questions closed.
3. about off-topic questions: New visitors surely won't come to first ask a question about the site itself. They just put their problem here without caring about whether a Meta site exists.
4. about MathJax: We mention MathJax (which is a good thing) but don't say how to make code boxes, although we know that many new people don't mark-down their code but rarely use formulas.

I suggest the following: let us use this first section where we still have the full attention of someone looking up the FAQ to say the most important things about asking a question here. In the comments to a question you can then really refer to the FAQ and the OP will know instantly what he did wrong.

Here a suggestion for such a first section.

Mathematica - Stack Exchange is for users of the software Mathematica and related products by Wolfram Research. If you have a question or are looking for help, please search this site before asking your own question.

Before you start working on your question, search the forum and check whether your problem has been asked before. If not, then be aware that only good questions receive good answers or answers at all. Good questions usually contain most of the following ingredients:

• a clear description of what exactly your problem is or what you are trying to achieve
• a minimal working code example of your problem or your efforts so that the other users here can try it for themselves
• an example of what you expect as output, if your code doesn't do what you want it to

As important as the content of your question is the formatting, because this makes your question easy for others to read. The toolbar on the top of the editor window contains most of the markup functions. Select a portion of text and then click the appropriate button.

As well as the editor buttons, you can format your post directly. For instance, if you want italics, type *italics* or if you want bold use **bold**.

Very important is that you know how to insert Mathematica-code into your post. To highlight a small part of code inline into your text, you can surround it by backticks. Therefore, when you want to speak about Plot3D you can insert this by typing `Plot3D` into the editor. More important is of course how to insert code blocks. This is done by inserting 4 spaces on the beginning of each line which is code. This is easily done by marking the code an by pressing Ctrl+K (Cmd+K on Mac) or by using the {} button in the toolbar. Two lines of code would therefore be inserted as

    f[x_]:=x^2;
    f[3]

A complete reference can be found found on the Markdown help page. Additionally, you can easily include mathematical formulas by using LaTeX-like syntax. Just enclose a mathematical expression in dollar signs, e.g. $[put math expression here]$.

In general, put as much effort into your question as you would like others to put into their answers. And be ready to reply to the comments on your question when it's posted.

It would be nice if some English native speaker corrects the text. Comments, additions, ... are very welcome. Just try to imagine you were completely new to this this and you stumble over this. Are you having enough information to ask an excellent question after reading it?

Answer 2

We should have a little bit about posting enough code to reproduce the issue, but not lots of extraneous code. I would also suggest that we say something about avoiding Mathematica special characters like \[CapitalGamma] because they make the code harder to read, like in this question.

Answer 3

I want to propose a link to the excellent Faysal's answer being part of the faq. Perhaps the question tile is a good link name (Where can I find examples of good Mathematica programming practice?)

Answer 4

We should get this moving, so I looked at a few other random sites' FAQ to get an idea about how this works:

• Math.SE

• Physics.SE

• CrossValidated

• Computational Science (this is a fresh beta)

• TeX.SE

• User Experience and Science Fiction (for some sites more different from ours)

I put some links here for your convenience.

One thing to notice is that usually the FAQ is modified only minimally: The first "What kind of questions can I ask here?" section is the most important, so we should take that first.

Here's a first draft (needs to be extended):

Mathematica.SE is for users of Mathematica. If you have a question about

• solving problems using Mathematica {or related companion products such as Player Pro, Player or Wolfram Workbench}

• Mathematica programming or the Mathematica language

• the Mathematica user interface (notebooks, customizations)

then you are at the right place!

Please try to include short code samples with questions when appropriate.

Maybe this is already too specific, and we can just say

Mathematica.SE is for users of Mathematica. If you have a question about the Mahematica system or wish to solve a problem using Mathematica, then you have come to the right place!

Another thing which has not been said explicitly, but I think we agree on is that this site is not only for questions about Mathematica, but also about questions on how to solve certain problems in Mathematica. For example, my question about adaptive sampling is really a numerical methods question, but when phrased as "what is the best way to get this done given Mathematica's capabilities", I think it's on topic, even if I don't yet have the specific algorithm for solving the task. On SO the reaction might be: first figure out your algorithm, then we'll help you implement it.

---

About What kind of questions should I not ask here? -- this is usually not modified on other sites, and I'm not sure we need it, but here are a few ideas:

Check the MathGroup rules: http://smc.vnet.net/mathgroup.html It gives some ideas about what people tend to ask which might be off topic.

Examples that shouldn't be asked here: questions about pricing/licensing (we're not WRI), bug reports (unless the question is about how to work around a bug)

---

Other ideas to include (I'll write lots, we'll need to trim the list. Also, these are not for different sections):

• How to write formulae (MathJax)

• How to post code (what format is preferred considering the REPL interface, and when to post math/images). The main idea here is: it should be very easy to copy the code back to Mathematica. Note: This is an important point, we just had an example of people pasting code as LaTeX for pretty (but uncopyable) formatting.

• How to easily upload images (do we need this at all, or keep it as a meta post only? does it make abuse too easy?)

• UX has a section about how to ask a good question. I don't personally think we need this (SO doesn't have it either), but it's another idea.

Finally, let me say that I think that a short FAQ is a good FAQ because people are more likely to read it.

Answer 5

A shortened and improved version of halirutan's suggestion. (The premise being that a short FAQ is a good FAQ:)

Mathematica - Stack Exchange is for users of the software Mathematica developed by Wolfram Research.

Before you start working on your question, search the forum and check whether your problem has been asked before. Be aware that only good questions receive good answers. Good questions usually contain most of the following ingredients:

• a clear description of what exactly your problem is or what you are trying to achieve;
• a minimal working code example of your problem or your efforts, formatted with Ctrl+K, so that other users can easily try it for themselves;
• an example of what you expect as output, if your code doesn't do what you want it to;
• some proof of a minimal Mathematica knowledge: be familiar with the language, its syntax, and the ways you can look for help. The searchable Documentation Center is included in Mathematica, and contains a full language reference, tutorials and guides.
• a title that clearly and succinctly summarizes your problem. That will help the right people to notice your question.

The formatting of your code is as important as its content, because it makes your question easier to read. Be sure to format the code by enclosing it with backticks (as in `code`) or by indenting lines of code by four spaces, which you can easily do by selecting the code and pressing Ctrl+K (Cmd+K on Mac). The toolbar on the top of the editor window contains other markup functions. Select a portion of text and then click the appropriate button.

Pay attention to Mathematica syntax, because code with erroneous syntax cannot be tested by others.

A complete reference can be found found on the Markdown help page. Additionally, you can easily include mathematical formulas by using LaTeX-like syntax. Just enclose a mathematical expression in dollar signs, e.g. $[put math expression here]$.

In general, put as much effort into your question as you would like others to put into their answers. Also, after asking the question stay on the site for a while as usually comments to your question will be quickly posted.

Answer 6

I think the FAQ should have a clear and detailed section, with examples, on:

• how to represent an Input cell on stackexchange

• how to represent an Output cell on stackexchange

• how to enter more complicated formatted notation on stackexchange ... the steps necessary to take a fancy formatted ratio equation input from Mathematica on your computer screen, and to paste it here, so that it presents nicely, not as Subscript[[Mu],1]^2/blah etc.

• for graphics: the html code for linking to your picture hosted elsewhere etc

I post here sporadically, and each time I come back, and have something to ask or answer, I have usually forgotten the tricks necessary (the 4 space rule, for instance), and have to go rummaging around trying to remember how I did it last time, which can be a bit frustrating.

Answer 7

I like the way the FAQ is developing. One thing that might be good to include would be links to some sample questions: ones with nice clear questions and nice clear answers. Perhaps placed below the bulleted items, such examples might be clearer to a new user than a set of instructions. It shouldn't be a lot, maybe just two or three, and they should be simple enough for a newish user to appreciate. I'm not sure I know how you would pick them!

Answer 8

I would like to see the following appear somewhere in the FAQ; maybe as a codicil to Question 1.

A very large proportion of the questions asked about Simplify result from the submitter assuming Simplify assumes by default that variables are in the domain of real numbers. It doesn't -- it assumes complex variables by default. Please review your assumptions before asking questions about Simplify.