Content Style Guide
##############################################################################

.. contents:: Contents
  :local:

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:

    .. image:: ../_static/img/scratch_say_block.png
      :alt: 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:

    .. image:: ../_static/img/scratch_multiple_join_blocks.png
      :alt: A screenshot of several join blocks together.

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

    .. image:: ../_static/img/scratch_set_block.png
      :alt: 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.