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.

share

8 Answers 8

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

enter image description here

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

enter image description here

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.

enter image description here

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?

share
    
Thanks @cormullion for the edit! Btw, I don't want the content of the first section deleted! What kind of questions can I ask here? should follow directly the first How to ask section. With this we could directly delete the MathJax paragraph from it because this has nothing to do with What kind of questions can I ask here?. –  halirutan Sep 25 '12 at 15:05
    
Edit wars -- I was just editing this:) –  Ajasja Oct 30 '12 at 14:18
    
@Ajasja I inserted a paragraph about inline and block code. It would be nice if you review it. –  halirutan Oct 30 '12 at 14:18
    
@cormullion, Would you too be so kind to have a look at the added paragraph about how to highlight code? –  halirutan Oct 30 '12 at 14:19
    
@Ajasja, oh. Then make the best of it. I stay out now. –  halirutan Oct 30 '12 at 14:20
    
No, No, I'll post it as a separate answer. We can always merge it back. –  Ajasja Oct 30 '12 at 14:27

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.

share

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?)

share
    
+1: at the very least it should be part of the tag wiki. –  Verbeia Jun 25 '12 at 6:00

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

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.

share
5  
The "What kind of questions can I ask here?" section of the FAQ is the only section that SE allows us to modify (except for the "What notation and symbols are used here?" section, for sites that have it). –  David Z Jan 29 '12 at 2:49
    
I prefer the dot-point version of the scoping description. I added some text in {braces} to explicitly include companion products - but we might need to be clear which ones are not in scope. See, e.g. here. –  Verbeia Jun 25 '12 at 6:07
    
I can heartily agree with the last sentence about conciseness. I never in my life read any FAQ-s at all in its entirety. I guess it is more there for reminding those to a fixed policy who complain about something post-facto, than for newcomers who (I guess) would rather read the tag wikis than the FAQ (or not even those). –  István Zachar Jun 25 '12 at 9:55

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.

toolbar image

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.

share
    
I've added the developer to further emphasize the differnece from mathematics, and also included a fourth point about knowing at least something about Mathematica. –  István Zachar Oct 31 '12 at 10:45
    
Also, we should include that it is unnecessary to put "How can I do ... in Mathematica?" into the title of the question. –  István Zachar Oct 31 '12 at 10:50

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.

share
    
All this information is available, but not in the FAQ. I agree with this suggestion, it'd be useful to have the information there. –  acl Mar 27 '13 at 18:38

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!

share

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.

share
    
That has limited applicability, and falls under the user should read the documentation. –  rcollyer Nov 16 '12 at 17:09
    
@rcollyer. It comes up a lot. I think new members -- the people who are most likely to consult the FAQ -- need some very specific advice such as this. –  m_goldberg Nov 16 '12 at 17:14
1  
You're right it does, which means we need a canonical question for it. But, as it in essence an RTFM question, it does not need special attention in the FAQ. –  rcollyer Nov 16 '12 at 19:04
    
I have to disagree. In cases like the implicit question being asked over and over again about Simplify, newcomers need a specific answer not a canonical one. If they consult the FAQ, they should find specific answers to the actual frequently although implicitly asked questions that come up. They will not connect generalities to their specific problems. –  m_goldberg Nov 16 '12 at 19:52
    
As is, a canonical question is the right place for this, as it deals with an issue with a specific function. That said, if we broaden it to something like "Mathematica makes few assumptions about the numerical types of its variables, and as a result it can give counter-intuitive results. Please review your assumptions before asking." to give it a wider application, then I can see it being included in the FAQ. –  rcollyer Nov 16 '12 at 20:14
    
@rcollyer. Ok, you've convinced me. I suggest you write up your canonical version of my question as another answer. –  m_goldberg Nov 16 '12 at 21:10
3  
Please see this and this as possible solutions. The FAQ is mostly about how to use the website/platform and what questions are on topic here, but not about how to use Mathematica –  Szabolcs Nov 16 '12 at 21:29

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .