Content Style Guide

Writing Style

When using pronouns in reference to a hypothetical person, gender neutral pronouns (they/their/them) should be used.

All documents (other than those for internal use only) must be written clearly and simply so that a non-expert is able to understand them. Preferably documents should be readable by students.

Any jargon used needs to be clearly explained and should be considered as a glossary definition.

Capitalisation Rules

In the majority of cases capitalisation should not be used for keywords and titles, with the following exceptions, where the phrase refers to a commonly used term that is often capitilised in the literature:

  • Computer Science.

  • Computational Thinking.

  • Digital Technologies (note that this is the correct form to refer to the subject area in NZ, with caps and plural; if it’s referring to something other than the subject then use lower case e.g. “smartphones and other digital technologies”, or even better, avoid the phrase e.g. “smartphones and other digital devices”).

  • Sorting Network.

  • Numeracy.

  • Literacy.

The following wouldn’t be capitalised: binary number(s), digits, binary digits

Extra notes for specific content

Glossary

The following are added to the glossary and linked to where the words are used:

  • All Computer Science, programming, and Computational Thinking jargon.

  • All education jargon.

  • All curriculum language that is not broadly used internationally.

Topic

Topic description must apply to all the units within the topic. It is one introductory paragraph, less than 150 words, which gives a big picture overview of why this topic is being taught/is relevant, and what it will cover.

Learning outcomes

Learning outcomes are written using language familiar to teachers and simple enough that it is understandable for students. Learning outcomes always begin with a verb.

Programming challenges

There needs to be enough scaffolding to support students to be able to achieve a result, independently.

When listing Scratch block:

  1. Separate out all the blocks that “click” together, leaving all the information inside where the parameter is written. All duplicates of a block should be displayed.

  2. Where a variable is inserted into another block, those blocks stay together, example below:

    A screenshot of a say block containing a variable.

  3. All join blocks are displayed as one and all the variables/text are included, example below:

    A screenshot of several join blocks together.

  4. For blocks containing join blocks keep the join block within the parent block, example below.

    A screenshot of a set block containing a join block.

  5. Loops should keep the condition blocks, but the blocks within the loop should be extracted.