The Quick and Dirty Rules

Writing Mechanics

• Don't make up your own names, use a name generator (or be extremely thoughtful about it).
  • Question to keep in mind: When was the last time I used a name more common in cultures different from mine?
  • One example name generator
• Use prettier.io and run this formatter after/during every change.
  • This helps the team conform on things like spacing, spaces, bullets, header styles, etc.
  • Exclude formatting for changes on config.yaml
  • This formatting 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
  • Assume that instructors/folks with direct relationships with students can say what not to 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)
• Every code challenge should have an example implementation in its explanation. Refer to the Templates and Stubs.
• Bold a vocabulary word represented in the vocab table the first instance it is introduced. Feel free to use italics to emphasize subsequent mentions.
  • Otherwise, prefer using italics for places of emphasis

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 can live as a moment in time, and a small thought)
  • Place value in understandable grammar and 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?
  • Emphasis is communicated differently between written and spoken word. Use visual cues, callouts, whitespace, section headers, italics, tables, etc, to create emphasis.
• 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?
• For complex or important concepts, repetition is great!

Grammar

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

• Write in the present tense
• If we must use pronouns, prefer "we" and try to make it clear who "we" is
  • Is it "we" developers in tech? Is it "we" educators? Is it "we" activists?
  • When possible, avoid identifying "we" as Ada Developers Academy staff-- this reinvokes the dynamic that the readers are not experts, and that Ada Developers Academy staff owns the curriculum and "are experts."
  • Otherwise, if not specified, "we" should mean "the Ada community members following this lesson and I, taking on the role of learners."
  • Using the second-person ("you") is acceptable during guided directions/steps.
• When giving directions or steps...
  • Put the steps in a list, or summarize the steps in a list
  • Write imperative statements as the first sentence per direction/step. ("Consider A," "Follow B," "Do C," "Answer D.")
  • Consider using second-person ("you") or third-person ("we"), but remain consistent throughout the entire lesson. Avoid mixing "you" and "we" in these sections, to avoid invoking a dynamic that separates the curriculum from the user.
• Avoid being referential to the curriculum directly; if we must invoke a previous or future lesson, refer to it by concept.
• If it is important to refer to a specific lesson, link to it directly as best as you can. Do not describe "where" the lesson is. It is better to have a link that will break in the future as opposed to directions on how to "navigate" to that lesson.
• If you are teaching an exception to a rule to something, separate this knowledge into its own paragraph, and away from a paragraph with definitions/introductions. This allows students to clearly separate what is typical and what is atypical.

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.