The Quick and Dirty Rules

Writing Mechanics

• Don't make up your own names, use a name generator (or be extremely thoughtful about it).
  • Questions to keep in mind: When was the last time I used a non-eurocentric name?
  • One example name generator
• Use prettier.io
  • This messes up Learn challenges. Refer to Templates and Stubs to find the prettier-ignore syntax
  • It also makes tables look weird. That's fine and a necessary evil (lol)
• Avoid the word "just" unless referring to the idea of "doing just enough"
• Do not use words like "simple," "obvious," "easy."
  • If you're trying to express that something is simple, then express it by writing a simple sentence, paragraph, or some other way.
• Headers should accurately describe the purpose of the section. A section header is the point of a section. The section itself should not have other major ideas; if it does, separate it into a different section/sub-section.
  • Don't introduce two major concepts in the same section and not refer to both in the header (or use sub-sections meaningfully)
  • Headers should be a spoiler for the section. If a student only reads a lesson's headers, they should be able to recall all of the major information in it.
• Only use code examples that show code we would want a student to write more than once
  • Don't present anti-patterns with code examples
  • If we don't want students to write that code, then don't write it yourself.
• Teach a lesson with the principles of what someone should do, rather than what they should not do
• Feel free to generate ids with short id or some other tool
  • Pro-tip: a word with no hyphens means that when you double click on it, it selects the entire word (rather than needing to use cursor movement or keystrokes to "aim" for selecting it). This is helpful when working on many lessons and challenges :)
• Challenge "titles" should be the name of the Lesson, matched exactly
  • Exception: Do not add the prefixes such as "Problem Set:" or "Activity: " because colons break titles (even in quotes)

Naming folders and files:

The name of a topic and the name of its folder should absolutely match, with different styles. Don't deviate or abbreviate or remove words, no matter how long it is.

• Topic name should be Title Case
• Folder name should be lower-kebab-case
  • ignore punctuation

Examples:

Topic Name	Folder Name
"Nested Data and Nested Loops"	nested-data-and-nested-loop
"Intro to Object-Oriented Programming"	intro-to-object-oriented-programming
"What is Software?"	what-is-software

The name of a lesson, the lesson file, and its top-level header should all absolutely match, with different styles. Don't deviate or abbreviate or remove words, no matter how long it is.

• Lesson file name should be lower-kebab-case
• Top-level header should be Title Case

Activites:

• Should prefix the lesson name with "Activity:"
• All the above rules apply

Examples:

Lesson Name	Top-Level Header	File Name
Raising and Handling Exceptions	# Raising and Handling Exceptions	raising-and-handling-exceptions.md
Problem Set: Functions, Continued	# Problem Set: Functions, Continued	problem-set-functions-continued
Activity: Intention Setting Our Careers	# Activity: Intention Setting Our Careers	activity-intention-setting-our-careers.md
Intro to Design Patterns	# Intro to Design Patterns	intro-to-design-patterns.md

The exception is Instructor lessons.

For instructor lessons:

• Prefix the lesson name with "Instructor:"
• The name of the lesson should be exactly the title of the lesson it refers to, or the overall topic if it's a general instructor file
• The file name must end in .instructor.md
• The file name should be the lesson name, without the instructor prefix

Config Naming Conventions

The description for every topic should be a comma-separated list of the lesson titles within it. Exclude non-student-facing lessons. Include everything else (each lesson, each activity, each problem set).

• Maintain the order that is set in the config
• Follow this rule even if this topic has only one lesson

Surround the description with double-quotes to preserve :s within this .yaml file.

Examples:

Topic: Fundamentals Recap Lessons:

• Fundamentals Vocabulary
• Conditionals Recap
• Problem Set: Fundamentals Vocabulary
• Problem Set: Conditionals Recap
• Math Primer

Description of topic in config: "Fundamentals Vocabulary, Conditionals Recap, Problem Set: Fundamentals Vocabulary, Problem Set: Conditionals Recap, Math Primer"

Topic: Fundamentals Recap Lessons:

• Fundamentals Vocabulary
• Conditionals Recap
• Problem Set: Fundamentals Vocabulary
• Problem Set: Conditionals Recap
• Math Primer

Description of topic in config: "Fundamentals Vocabulary, Conditionals Recap, Problem Set: Fundamentals Vocabulary, Problem Set: Conditionals Recap, Math Primer"

Topic: Intro to Dev Environment Lessons:

• Instructor: Intro to Dev Environment
• Intro to Command Line
• Intro to Computer Memory

Description of topic in config: "Intro to Command Line, Intro to Computer Memory"

Big Principles

• Writing is different than conversation
  • Conversational tone and levity is good! Don't take that away
  • Written words are not ephemeral-- a tangential paragraph that takes up a lot of space detracts value from the lesson (whereas a tangent in a conversation
  • Place value in grammar, clarity
  • Reading is hard. Consider the amount of mental work it takes to get through your paragraph. Gut check: If someone told you the sentence in a coffee shop, would you be able to hold the sentence in your head?
• Put effort into formatting, organization, and structure of words, punctuation, headers, etc.
  • The markdown that you write is the markdown that all instructors will wade through. Have compassion for your future self-- delete comments, condense spaces when possible, and use ample whitespace to help someone read the markdown.
• Prefer shorter paragraphs. One-line paragraphs are valid and should be used often.
• Every sentence should contribute meaning to the lesson, and meaning to the student.
  • Each student carries the expectation that each sentence presents new information that would serve them if they absorbed it.
  • Evaluate each paragraph: If a student got "hung up" on this paragraph, would it have been wasted effort?

Git Commit Convention

Prefix the commit message with the name of the lesson (lower-kebab-case) that is changed in this commit.

If the commit changes multiple lesson files, prefix with the name of the topic (lower-kebab-case) that is changed in this commit.

If there are multiple topics being affected:

• Consider making separate commits
• If it's the best option to keep it in one commit, forget the prefix, and mention the topics affected in the message

Examples:

• intro-to-computer-memory: cleans up leftover storage unit metaphor
• practice-iterating-over-data: reformats, spacing, conform challenge titles
• oop-relationships -> intro-to-oop-relationships, break away composition
• config: adds practice-intro-to-pytest and math-primer
• config, ada-orientation: deletes ada-orientation content
• iterating-over-data: formatting, small grammar fixes

This convention allows for team members to more easily see what files have been affected since the last time they checked the repo commit history, without needing to go to the files themselves or the commits themselves.