Help spot deficiencies in our Help Center

Question

Regular participants will be familiar with procedures and practices on Code Review. For example, we have rules against

• asking hypothetical questions
• appending to or modifying the question after receiving answers
• answering in comments, even if the answer is brief

Those practices have been developed by the community, and are written in our Meta site. However, new users are often unaware of these rules until we point out their violation. This leads to unnecessary frustration and embarrassment.

Instead of expecting new users to wade through Meta posts, we should have a Help Center that effectively teaches new users how to thrive on Code Review. Unfortunately, many of our current Help Center pages contain generic text that is incomplete or inappropriate for Code Review.

Could you please help point out any deficiencies you find in our Help Center pages?

This post focuses on identifying the deficiencies. Drafting of the new pages is in this follow-up post.

Answer 1

What should I do when someone answers my question?

The page needs to mention that incorporating suggestions from answers into the question is unacceptable. It should also suggest options for follow-ups (posting a self answer or a second question). Basically, it needs to include a summary of the advice in this answer.

Answer 2

The How to ask page is a little lacking. It doesn't mention that we expect titles to describe what the code does, not the concerns about it.

The "Be specific" section could also be polished up a bit. I'm not sure how to go about it, but we should be specific about being specific. In my mind good questions detail both the purpose and methodology of the code in a reasonably detailed way. We should say so in that section.

I think the "Make it relevant to others" part can just jump.

Answer 3

What should I do if no one answers my question?

If no one answers, try The 2nd Monitor? Maybe the question is too vague, too confusing, too complicated, or just happened to fall through the cracks. In any case, mentioning it in the chat room can help.

Answer 4

https://codereview.stackexchange.com/help/tagging

Regarding tagging...

Each question may only contain 5 tags at a maximum, so choose the ones that best describe your question.

"Please fix my duplication" -> duplication

Could we change this to "that best describe what your code is about." This strangely seems conflict with beginnerperformancetime-limit-exceededcomparative-review though. Hmmh.

By the way, that same page states:

Meta-tags, like [beginner], [subjective], and [best-practices], are not helpful by themselves – they do not communicate anything about the content of the question.

---

Should I use tags in titles? You should not force a tag into your title. Because the tags appear below the question and tags are indexed by search engines along with the content of your question, you can trust that other people will be able to find your question based on tags they follow or search for. Additionally, tags appear on the question page, so other people will take them into account when answering your question.

Avoid inserting tags into titles in any of the following formats:

• [tag]: [question title]
• [question title] -- [tag] [tag] [tag]
• [question title] in [tag]
• [tag] [tag] [question title] [tag] [tag] [tag]
• [tag] [tag] [tag] [tag] [tag] [tag] [tag] [tag]

The only time you should use tags in your title is when they are organic to the conversational tone of the title.

For example, rather than writing, JavaScript, jQuery: When should I use one or the other? – which forces tags into the title – you can convey the same information in a conversational tone:

Can I use jQuery to foo the bar on the baz, or am I stuck using plain JavaScript?

I think we could use this to toss in some title advice.

Answer 5

How do I write a good answer?

This paragraph is a non-sequitur (for any site, not just Code Review):

Pay it forward

Saying “thanks” is appreciated, but it doesn’t answer the question. Instead, vote up the answers that helped you the most! If these answers were helpful to you, please consider saying thank you in a more constructive way – by contributing your own answers to questions your peers have asked here.

This paragraph is generally useful, but not quite accurate, since answers may address any aspect of the code:

Answer the question

Read the question carefully. What, specifically, is the question asking for? Make sure your answer provides that …

We have so many more useful points to discuss than grammar, and furthermore, even answers with basic English can do reasonably well.

Write to the best of your ability

The following points need to be qualified or dropped, since our answers are mostly subjective, and we are quite liberal about duplicates:

Answer well-asked questions

avoid trying to answer questions which...

• …solicit opinions rather than facts.
• …have already been asked and answered many times before.

---

Instead of platitudes, I'd really rather talk about what makes a good Code Review answer. For example:

• Code dumps without explanation and alternate solutions without justification are unacceptable.
• Short answers are acceptable here, as long as justification is included. Answering in comments is not acceptable.
• Answers should be tailored to the apparent ability level of the author of the code.
• Organize your thoughts; sometimes less is better.
• Highlighting the positive aspects of the code is also appreciated.

Answer 6

What types of questions should I avoid asking?

Much of the text is irrelevant or inaccurate for Code Review. In my opinion, the whole page needs to be rewritten.

You should only ask practical, answerable questions based on actual problems that you face. Chatty, open-ended questions diminish the usefulness of our site and push other questions off the front page.

If your motivation for asking the question is “I would like to participate in a discussion about ______”, then you should not be asking here.

Our problem is not so much unanswerable open-ended questions. Rather, we should reiterate the importance of posting real, non-hypothetical code samples. To be clear, there should be an example of a bad hypothetical question and a good concrete question.

---

Considering the example genres of questions…

• every answer is equally valid: "What's your favorite _____?"

I don't think we've ever gotten one of those questions, and if asked, it would be off-topic anyway. Also, it's often the case that there are many good approaches to recommend.

• your answer is provided along with the question, and you expect more answers

We get comparative-review questions all the time, and they're fine.

• there is no actual problem to be solved: "I'm curious if other people feel like I do."

Almost every code sample can be improved, even if there's no explicit question. Almost every Code Review question is a variant of "I'm curious if other people feel like I do."

• you are asking an open-ended, hypothetical question: “What if ______ happened?”

Hypothetical questions are one of the few types of prohibited questions. As discussed above, we should clarify what that means.

• "_____ sucks, am I right?"

The whole site is about "does this code make my ass look fat?"

---

Some subjective questions are allowed, but “subjective” does not mean “anything goes”. All subjective questions are expected to be constructive.

That's true, but more confusing than relevant. As long as the question includes a code sample that meets the on-topic rules, it's going to be fine. So let's not bother explaining good-subjective / bad-subjective to new users.

• invite sharing experiences over opinions

That's not quite correctly worded. Opinionated answers are fine — they just need to be justified with some reasoning.

Answer 7

How do I format my posts using Markdown or HTML?

This is good stuff. However, more guidance needs to be provided for how to copy-and-paste code blocks with the proper indentation — we get incorrectly indented code all the time, and it's confusing and frustrating.

There should be a basic MathJax guide. I don't think that Code Review should write it; Stack Exchange should just provide a standard page for sites that have MathJax enabled (perhaps with input from the Mathematics community).

Answer 8

Our six magic on-topic questions should be reordered according to how common it is to answer "no". Currently:

• Is code included directly in my question? (See Make sure you include your code in your question below.)
• Am I an owner or maintainer of the code?
• Is it actual code from a project rather than pseudo-code or example code?
• Do I want the code to be good code? (i.e. not code-golfing, obfuscation, or similar)
• To the best of my knowledge, does the code work as intended?
• Do I want feedback about any or all facets of the code?

Note here that "Does the code work?" is probably the most common reason we close questions, but it currently appears second to last.

Answer 9

https://codereview.stackexchange.com/help/on-topic

Make sure you include your code in your question
This site is for code reviews, which are hard to do when the code is behind a link somewhere out there on the Internet. If you want a code review, you must post the relevant snippets of code in your question. It is fine to post a "see more" link (though, do be careful — very few reviewers will be willing to click through and read thousands of lines of your code), but the most important parts of the code must be placed directly in the question.

I don't agree with the "relevant snippets". It's hard for users to put the relevant snippets in, as they often go for not enough.

I wish people would post...

• A single function
• or a set of functions
• or a whole class
• or a bunch of classes (This is on the border of okay, it's hard to review big questions).

rather than lines from here and there.

Could we alter it to say "A good amount of code for a review question is one or a few functions, or a single class. Having multiple classes in your question is okay, but they should be related to each other."