17

I've been reviewing first posts and late answers for about a month now. At first it seemed obvious what I should be doing: fix up the English in poorly written posts. I feel qualified to do that; I did a lot of technical writing in the fifty years before I retired.

Now I've come to believe reviewers are expected or at least encouraged to do more. Flag inappropriate posts and fix really bad markdown, to give two examples. My question: is there a FAQ for reviewers that can I read to find out all the things I ought to be doing? And, if not, should there be?

I searched for such a FAQ, but didn't find anything. Might have missed it, though. I'm not so good at choosing search keywords.

2
  • 9
    I noticed your heavy editing, since with your current rep someone has to approve your edits. I just wanted to say, I really appreciate them. I barely have to look over your edits, because I know they are good. Excellent work.
    – halirutan Mod
    Dec 14, 2012 at 4:22
  • 1
    Yes, I'll echo Mr.Wizard and halirutan in saying thanks for your frequent and good edits :)
    – rm -rf Mod
    Dec 14, 2012 at 4:33

3 Answers 3

Reset to default
17

We agreed on several style things which were discussed in different places and are probably hard to find. From the top of my head, I can name some editing things which should be done:

  • We decided to always emphasis the word Mathematica. This includes converting things like MMA.
  • In a post, Mathematica functions like Plot should be marked as inline code. When it doesn't destroy the readability and it is helpful for the understanding, I sometimes do this even when the function name is only used as normal word, like in: I tried to Export my data into an excel file. I don't know whether we agreed on this, but it is helpful since you instantly see the function used.
  • I myself often fix indentation in code blocks when I think the block is badly indented and the indentation was not on purpose.
  • I shorten code lines, so that the scrollbar disappears.
  • In code blocks, which are not Mathematica code, you can use the language hint to ensure proper highlighting.
  • I often remove Thanks endings

Additionally to our FAQ, the What should our FAQ contain discussion shows, what hasn't made it to the final FAQ.

3
  • 3
    +1, however I actually disagree with the second point, in a way. I used to follow that guideline rigidly but in time I started to internally distinguish between references to specific functions and references to those functions as concepts or categories, where continuous code tags only make reading harder and may even cloud the meaning. This is a nascent principle and I need to give it more thought; perhaps a Meta post is in order.
    – Mr.Wizard
    Dec 14, 2012 at 4:37
  • 1
    I agree, this is something I generally fix in a post too. As for the marking keywords that match function names as inline code, I prefer doing that only when that function is the subject of the question. Otherwise, treat it just like any other English word. For instance, if the question is on export issues, this: "I tried to Export a plot of a histogram from my data, but..." is preferable to "I tried to Export a Plot of a Histogram from my data, ....". The latter gets annoying when the words keep repeating and is highlighted everywhere.
    – rm -rf Mod
    Dec 14, 2012 at 4:39
  • No, you are right. In a long description I skip this sometimes too, in order to make it better readable. I will edit this..
    – halirutan Mod
    Dec 14, 2012 at 4:39
8

There are some threads on Meta.StackOverflow about this, such as:

Can we agree on a review 'policy'?

As someone who has approved a number of your edits I say thank you for the hard work.
Certainly nothing more is expected of you.

If you are looking for additional tasks in your reviewing I ask that you help identify near and exact duplicate posts. There are far too many questions on this site even for those with a much better memory than mine to keep track of (though R.M in particular tries hard). When you find one please flag it. If you are not sure it is a duplicate you can still flag it as "Other" and make a note of the post(s) that you believe are duplicated, and please add a comment below the post in the form: Related: (link).

You may also consider adding links to the official documentation as even if these pages are easy to find it is more convenient to have them linked.

4
  • 2
    A point to note: That question is for the older /review page. It was revamped heavily sometime mid 2012 and is also tied to badges, which has led to users gaming it (I haven't seen anything like that here). Some relevant discussions: meta.stackexchange.com/q/149621, meta.stackexchange.com/q/158418, meta.stackexchange.com/q/157856, meta.stackexchange.com/q/157121. The bottom line is: there is no established guideline beyond "do your best to fix the post (formatting, typos, grammar), comment to educate, upvote if good, downvote + close/flag if bad, or ignore if meh"
    – rm -rf Mod
    Dec 14, 2012 at 4:29
  • @rm-rf I've seen several of those and voted on one of them. I guess I should have said something like that in my answer. My intention was to provide a link to MSO for anyone curious enough to dig into that, but then primarily give my thanks and state a couple of personal reviewing priorities.
    – Mr.Wizard
    Dec 14, 2012 at 4:33
  • @Mr.Wizard. I'm glad you provided the link to the discussion of reviewing on meta.stackoverflow. I found it interesting, and I think it will be useful to me. I'm happy to say I've never seen some of the problems they discussed.
    – m_goldberg
    Dec 14, 2012 at 5:50
  • @rm-rf. Thanks for your summary of current policy. It's pretty close to personal policy I had worked from doing reviews. I'll now do my best to make my it my policy, too.
    – m_goldberg
    Dec 14, 2012 at 5:55
4

I was going to respond to Halirutan's thoughtful answer, but I think this deserves more than a comment.

I am among the most ardent supporters of re-formatting code for readability. First, the code should not require the user to side scroll, it interrupts the flow and often it is just one very, very long line. Second, the indentation should be set up in such a way to easily understand where the beginnings and endings of functions and lists are and the structure is clarified. This helps in making the code more comprehensible, quickly. Third, remove all Mathematica mark-up if possible. For the Greek letters, I will often replace the mark-up with the unicode version which is still understandable by Mathematica, and now human readable.

The last point requires caution in application. On at least one occasion, my fixes to the mark-up have fixed the OPs problem, so on more complex transformations, you may have to re-run the code to ensure the problem remains. Also, the more extensive mark-up, e.g. 

\!\(
\*UnderoverscriptBox[\(\[Sum]\), \(i = 1\), \(5\)]
\*FractionBox[\(1\), 
SqrtBox[\(i\)]]\)

can actually conflict with the escape sequences in the displayed form. So, when converting the above to a usable form

Sum[1/Sqrt[i], {i, 1, 5}]

you should copy the text from the edit window, not the result window. Lastly, when a user posts such a mess, I leave a note asking them to first convert their input to InputForm using either the context menu (right click) or the Cell menu before posting next time.

You must log in to answer this question.

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