Guidelines for writing problems

Introduction

These authoring notes were originally written for the use of Grok staff in authoring problems. Many of the points apply to external authors, especially legal issues.

We recommend authors follow our own guidelines where possible. However it's your responsibility as an author to understand your own institution's principles, styles and rules for authoring content.

Problem Writing Style

  • Keep the question text as short as possible without losing some creativity.
    • Reading a lot of material is a barrier to entry to a lot of students.
    • The easier the question is the shorter the description should be
  • Beginners questions should typically be <= 2 short paragraphs
  • Make sure language is appropriate for the reading age of the students
  • Check your spelling!
  • Images are good if they add something to the question

Problem Titles

  • Titles should be puns, idioms or popular culture references if possible, but they should not be too forced, or too esoteric.
  • Only the first word of a title should be capitalised, except where the other words are part of a proper noun. Within proper nouns, function words should be lowercase, e.g. of in University of Sydney.
    • Except... Web Comp problems have all words in their titles capitalised.

Problem Content

  • Content should be age appropriate
    • Examples and jokes should be acceptable to parents of the relevant age group
    • Examples should be relevant to that age group (e.g. “starting a business” or “voting in the election” is probably not relevant to 10 year olds)
  • Check content is free from racism, sexism, homophobia or any other form of discrimination.
    • Remember our audience is worldwide
  • Content should be free from political bias or other types of bias.
    • We are teaching coding to everyone: conservative, progressive, religious, atheist...
  • Keep in mind diversity when creating content
    • Avoid too much nerd humour - all kids are doing this, not just geeks/nerds
    • Remember to include female and male oriented topics (fashion as much as cars)
    • Remember to use both male and female names, and from different ethnic backgrounds (not all “Jack” and “Jane”)

Educational Principals

  • Use only material that has been covered in the notes up until that point.
    • Avoid ‘hint’ boxes that cover new material because the question requires it.
  • Make sure the questions cover a reasonable range of the material in that week’s notes
  • Check the question hasn’t been used within the last 2 years?
  • Check the question isn’t the same as an example in the notes
  • There should be a mix of ‘language’-based and ‘maths’-based questions
  • All questions should have a “your program should work like this” example.
  • Difficult questions should be challenging, not “tricky” - i.e. even hard questions should still be clearly explained, without traps or unnecessary complexity.

Problem Coding Style

  • Make sure sample solutions only use coding constructs that have been taught
  • Use underscores rather than camelCase, and use variables as per: ingredient1
  • Give the simplest (easiest to understand) solution before other, more complex, solutions.

Problem Test Cases

  • The first test cases should test the examples in the question.
    • If this isn't possible, the question should be reworded.
  • Test cases for easy questions should all use the output ‘diff’ feature so students can see what their solution output (compared to what it should have output).
  • There should typically be at least one hidden test case.
  • Pass message should be consistently of the form: Testing a/the/that
    • We want students to understand that we’re testing their code to mark it
  • Fail message should talk about the program, not the student.
  • Tests should be ordered logically to follow the expected implementation order but also with an eye to giving students as much positive feedback early on as possible.

Problem Accessibility

  • Questions should not depend on colour in a way that excludes colour-blind students
  • Be careful about using complex Unicode characters. Some characters (e.g. non-English scripts, emoji) are actually multiple Unicode characters combined, and can look identical to users while still being different to a differ test case.

Legal

  • Don’t use images unless we have permission for commercial use (e.g. Creative Commons).
    • Provide a source for all images.
  • Don’t link to external content that isn’t age appropriate or may be blocked by schools filters
    • Remember our target audience is not university students, but school kids/parents
    • Be aware of wider site content - students might end up 'one click away' from inappropriate content. (e.g XKCD).
  • Don’t link to unofficial YouTube songs/movies etc.