Develop guidelines for problem statement structure and wording

[ldwoolley]

@vpavlenko As I have been working the problems, I am noticing a variety of ways to structure the problem statements. I think it might be beneficial to create a simple standard that is followed, and then every update should approach the standard. One possible start:

Consistent order:

1. Given (use input())
2. Goal/objective for the code
3. Output (use print())
4. Restrictions/Don't use

Use of Math structures:

• Favor the problem written in simple English phrases.
• Mark declared variables as math symbols
• Use mathematics expressions when the English will be complicated or confusing or really long.

What do you think?

[vpavlenko]

@ldwoolley Thanks a lot for formulating this issue. In many other websites problem statements follow the uniform structure with Statement / Input / Output. Historically, it wasn't the case on our platform, but I think it may be better if we now move to that uniformity. I plan to make this move myself during May 2017, when I plan to massively refactor the content.

[ldwoolley]

How about I add a description of this goal in the README.md file that provides this outline. It might encurage more changes to move this direction, if/when someone else offers a suggestion. Do you want this to go on the main snakify/content README.md or on a new README.md inside problems. These directions would only apply to the problems group. We can keep updating the directions as we decide on improved rules for consistency.

[vpavlenko]

This is a good idea. However, I think it's not worth putting these guidelines to README.md right now as there are almost no teachers viewing this repo anyways. Let me put it after I refactor the content in May 2017 and work out final guidelines based on these ones, after I have enough experience and vision on how to shape our problems. It may be that we add many problems in May 2017 or something like that, as well.

[johnkershaw]

I'm a teacher and I'm viewing the repo :)

a) I agree think it would be a very good idea to embed this in the README.md

b) I would stay away from math examples and prefer simple examples from normal life. Problems should be derived from the domain of the reader, not the domain of the programmer. We cannot know their level of math ability/comfort, but everyone exists in the real world and is more likely to understand examples matching their everyday existence.

c) I'd agree with Statement / Inputs / Outputs. Learners should keep the purpose of the code in the front of their mind. Why am I doing this? Have I tried giving my code bad / edge case inputs? The sooner students can begin to come up with their own problematic inputs to their code, the sooner they'll graduate to coming up with entirely new problems, and solving them. Only when they start to transfer skills learnt here into their 'normal' lives has real learning occurred.