Writing Style Guide

Writing Style

Having a writing style guide allows our voice to be consistent and unified. A consistent and unified writing style:

• Gives better clarity and lessens confusion to learners
• Creates less decision points to curriculum developers
• Allows content-deliverers to focus on content rather than structure or grammar

Voice

"We" refers to "those who develop and use this curriculum."

• We are friendly and honest, but not pretentious or timid.
• We are confident, and confident in not knowing all the answers.
• We value compassion over being correct.
• We prefer making our curriculum accessible to the most marginalized community members.
• We freely express emotion, especially joy, in our curriculum. Connecting on emotion lightly every now on then helps us connect with our content more intimately. Expressing joy in our curriculum helps create strong, positive memories. Expressing angst in our curriculum helps create a shared sense of belonging.
• We openly acknowledge the role of oppressive systems in the tech industry.

We value fun curriculum

• We use humor and lightness in our text as a way to make our curriculum approachable.
• We prefer making our curriculum hands-on and interactive, with frequent prompts to research, hypothesize, question, answer, practice, or reflect. We believe this increases joy!
• We make space for the unexpected; allowing for sponteneity gives us time and space to pursue fun, interesting topics that individuals want to go deeper on.

We value accessible language

Accessibility in our curriculum voice means intentionally increasing access to effective understanding to all kinds of people in our writing style.

• We prefer finding analogies, metaphors, and references that are multicultural, or that can be linked to an external source (Wikipedia, etc.) for more context.
  • A metaphor that takes more than one paragraph to define/start may lose people.
  • If the analogy/metaphor/reference that we want to make is not accessible, we will prefer to find a different analogy or to not use an analogy.
• We avoid run-on sentences. Run-on sentences disadvantage folks who don't excel at reading English.
• We enjoy intentional story-telling when it advances the learner's understanding of the concept. Story-telling helps engage learners and allows them to understand the sequence of a concept. Stories guide learners to a conclusion.
• We value respectful language.
  • We avoid serious sarcasm on serious subjects in our text, even if it may come into our teaching. We might include sarcasm about literal programming concepts in our text as a way of being accessible.

We value a self-sufficient, empowering curriculum

• We want learners to be able to say, "I could learn this on my own using these materials."
• We desire to develop a sense of ownership in the learner.
• We assume the reader is intelligent and is capable of knowing and doing things.
• We want our curriculm voice to capture not only facts about programming, but also facts about deeper thinking.
• We enjoy modeling the value of not knowing everything.
  • We believe "it's okay if I don't understand everything about this lesson right away" and "I don't need to know everything," and we share that believe through our curriculum.
• We do not assume access to objective truth. We celebrate the gray-- there is not one right way or one right answer.

Lesson Structure

A lesson is something that teaches/introduces knowledge for 1-5 specific learning goals, reinforces knowledge for 1-5 specific learning goals, or practices a skill for 1-5 specific learning goals.

There are three kinds of lessons:

1. Content Lessons
   • Best for teaching or introducing knowledge for 1-5 specific LGs.
   • Great at the "Knowledge," "Understanding," and "Applying" levels of Bloom's Taxonomy.
   • Content Lessons will have 0+ sections that are either focused on teaching a concept, or guided directions for implementing something.
2. Problem Sets and Activities
   • Best for reinforcing knowledge or practicing a skill for 1-5 specific LGs.
   • Great at the "Knowledge," "Understanding," and "Applying" levels of Bloom's Taxonomy.
   • Problem Sets and Activities will have 1+ sections that outline the expectations, how someone knows they've met the expectations, and the directions to lead to that goal.

As per our curriculum philosophy:

• Motivate students with problems that are: relevant to their lived experiences and realistic in software dev. Relevant is more important than realistic.
• Teach the conceptual approach first.
• Then teach how to practically solve the problem.
  • Then give directions to the correct solution.
• Rehearse this enough until learners can start making unique solutions themselves.

Structuring a Content Lesson

Content lessons are a type of lesson.

Overall, lessons, or very large sections of lesson, should try to follow this format as much as possible:

1. Say what we need before we get started (Required materials, Learning objectives, etc)
2. Say what you will say
3. Say it
4. Say what you said
5. Lesson meta stuff (contributors list, etc)

With more detail...

1. Provide a list of the most related pre-requisites to this lesson. Pre-requisites are materials (lessons, projects, problem sets, videos, homework, etc.) that are needed before the learner even begins this lesson.
2. Provide the Learning Objectives and the lesson video
3. Provide theory/motivation/background/context. This is ideally more of a "story." It shouldn't teach anything at this point. The purpose of this section should be to
   • Convince the learner that what we're about to learn is worth learning about.
   • Get the learner to start thinking the right headspace (are we learning about syntax or team practices or CS theory or pedagogy or social justice or software?). Get them to think in the right level of abstraction.
   • Get the learner to be curious about what they're going to learn!
   • If there is a reference to pop culture, certain histories, etc. that should be explained, explain it, even if it feels like 99% of readers will understand it. In general, a sentence defining something and linking to a Wikipedia page or a YouTube video that defines it will do.
4. Clearly mark all definitions that can be introduced at the beginning.
5. Spell out what the structure of the lesson will be, preferably in a list. If you use a list, each list item in this list can/should match/correspond to a header inside this lesson.
6. Deliver lesson content with a combination of text, code snippets, images, diagrams, tables, lists, and questions.

Tips About Designing Lesson Content/Flow

As much as possible, as long as the context allows...

• Each section should strictly be about only one of the following : Theory/motivation/background/context/definitions/summaries, OR showing/explaining syntax, OR follow-along exercises.
  • When we are tempted to have a section that is displaying many of these, split them into different sections.
• Start each lesson with a section on theory/motivation/background/context, even if it is a sentence long.
• Name the header of each section with the literal takeaway of the section. Ex. "Variables are References to Values in Memory."
  • Avoid making the header of a section be mysterious or vague simply for the sake of suspense (Ex. "Now what do we do...?"). If the header of a section is ambiguous about what it's teaching, it should be intentional.
• Every paragraph should be moving a reader closer to one of the lesson's stated learning goals. Otherwise it is a tangent.
• Separate tangents that aren't necessary for the learning objectives into its own paragraph, callout, or section.

Learn LMS Tips

• For a lesson that is not review (and is delivering new content), avoid having more than 3 Learn questions per lesson (5 for a very long lesson).
• Use Learn questions to reinforce the absolute bare minimum of the stated learning goals.
  • Avoid Learn questions that test on details unrelated to the stated learning goals.
• Intentionally scale the difficulty of questions (start easy, so that they build up to help answer harder questions).
• Prefer having the Learn questions at the end. Avoid having Learn questions scattered through the middle, unless they are intentionally telling a story, helping with the lesson structure, or breaking up the pacing.
  • Frequently breaking up a lesson with Learn questions in order to help pacing might be a sign that the lesson is too big.
  • Having checklists in the middle of a lesson, especially during a section that describes steps, is a good pattern.
  • Well-written Learn questions stick in the memories of students, and many will want to return to them again. By keeping them typically at the end, students will be able to navigate to the memorable questions faster, and speed up their learning.
• Use "callouts" to distinguish tangents.

Problem Sets

Problem Sets are a type of lesson.

Overall, problem sets should try to follow this format as much as possible:

• Use as many different kinds of exercises as possible (reflection! multiple choice! draw a diagram! pull out cards!), but refer to the Toolkit for inspiration.
• For coding problems, make it testable.
• For reflection/text/short answer/long answer problems, do not validate the input.
• Ensure that the solution to a problem can be found with what has been taught in the curriculum.
  • Do not teach a concept through a question.
• Be intentional about the sequencing of questions. Start with a straightforward question at the beginning, always. An exercise with an inappropriately tough first question is discouraging.
• Write questions that are challenging and reinforcing a learning goal; always avoid write "trick questions."
• For questions given in plain text (withou a Learn LMS question), explicitly define how the learner knows they have finished the problem/direction/exercise.
  • Use time frames (8 minutes, 15 minutes, 20 minutes), an amount to write (1 paragraph, 2 paragraphs, 5 questions, 2 takeaways), or anything else!

Assuming each question takes about 30 seconds-10 minutes to answer...

• For a long exercise, aim for 2-6 questions per learning goal.
• For a medium exercise, aim for 1-3 questions per learning goal.
• For a short exercise, aim for 1-2 questions per learning goal.

Structuring a Problem Set

Overall, exercises should try to follow this format as much as possible:

1. Say what you need before you get started
2. Say what you will do
3. Say how to do it, and how they know they're finished
4. Throughout the exercise or at the end, the exercise should provide feedback or outline how there could be feedback (or if there will be no feedback)