Style

Making With Code content generally falls within the genre of narrative software documentation. However, Making With Code's intended audience is high school students taking their first computer science course; tone and structure are very important for creating a welcoming, playful, exploratory atmosphere.

• Students who are unfamiliar with software documentation or other technical writing often need support learning to read the genre. Such students may have developed reading practices of quick skimming when reading online; documentation requires careful attention to details.
• Keep in mind that students may need to have multiple windows open: the MWC website, a terminal, a text editor, and perhaps others. This introduces significant cognitive load, so it's important to be clear about what students need to do at any particular time.

Content types

Labs

Labs are meant to guide groups of students working together to explore new ideas.

• When students need to do something, use shortcodes to express intent. Show expected results of actions so that students know they are on the right track.
• Support groupwork by introducing checkpoints in labs. Teachers can use checkpoints however they want, but it often works well to require groups to check in with the teacher before moving on from a checkpoint. This is an opportunity for the teacher to check for group dynamics--for example, by asking individual group members for their understanding of the completed section to ensure that everyone in the group is taking responsibility for everyone's learning.

Problem sets

• Keep in mind AI usage...

Projects

Projects are open-ended opportunities to apply learning.

In specifying a project, it is a good idea to be clear about requirements.

• Use a

Code

• Use fenced code blocks to represent source code.

  $ pwd
  /Users/chris
  

  def fibb():
      "An iterator over the fibonacci sequence"
      a, b = 1, 0
      while True:
          yield a
          a, b = a + b, a
  

• For interactive shells such as the command prompt and Python's REPL, show output as it will appear to users.

  >>> 1+2
  3
  

• Use line numbers when the text will refer to specific elements of the code.

• Use $ to represent the command prompt. When filesystem locations are important, use ~/Desktop/cs9/unit_00$.

Open issues