General guidelines for language references

Question

This question is a follow-up to Create a reference for newbie common mistakes.

I'm trying to understand/outline how these language references should look like.

What do you think should be put in them, and what not?

Edit: I'm not trying to adress specific things to put in them, but a general guideline to follow, so who want to partecipate can come here, see what we agreed on to build and jump along with us :)

As of right now we're just trying to start with the right foot, I agree that for sure we'll see later what works and what not (and maybe come back here to talk about it).

Answer 1

I think the best way to flush out what should go in and what shouldn't is to take it on a per-example basis. Start out with 1 question using generic phrasing for some language, like:

What are some common ways to improve Python code? One example per answer, please.

As answers are posted, the community can re-evaluate the scope of the question and make changes as necessary. Perhaps this question can be updated with the accepted phrasing, and then anyone can use it to create a new reference for a specific language.

• Quentin Pradet: I think that's the best way indeed. The Area51 way, which also worked well to refine the scope of CodeReview.
• Rik Poggi: I agree that that is the best way, I was trying to build some common ground for the very start and maybe a place where to come back later once we'll have clear ideas.
• Rik Poggi: I'm not saying that we should spend much time at this stage, but a little should not bring any harm (imho), like a little design session before coding.

Answer 2

I think these language references should be addressed to newbies.

Intermediate and advanced levels could be wrote later:

• It's best to start with simple things.
• Maybe we'll never even need them, we'll see how this newbie goes.
• If goes well, well these levels should be in a separate "session" anyway.

I'd say that we should try do adress those newbie's common mistakes that we so often see here on code review.

I think that we should not build a duplicate of the official doc or some kind of tutorial.

This is something different, something that newbies will read after having already written a working piece of code. That said I think that linking to the official doc is good, providing an official reference is always a good thing.