Skip to content

Editorial and Pedagogy Standards

Description and Purpose

This document covers editorial and pedagogy standards to be used across all content types.

Editorial

Codecademy uses APA to guide the style and grammar in its content. If any editorial questions you have are not addressed in the following content, visit the APA Style website for guidance. If the guidelines on this page, or in other Codecademy resources, contradicts APA style or grammar guidelines, follow the Codecademy standards.

General

  • Written content is free from spelling, punctuation, and grammatical errors. The free Grammarly plugin is also a great way to keep an eye on your grammar, though it’s not 100% accurate.
  • All text is formatted using markdown that follows the markdown style guide.
  • The language used is clear and unambiguous. For example, refer to specific topics and terms by name rather than using vague pronouns like “this” or “that”.
  • The language used is precise (consistent). For example, don't refer to something as a "method" in one place and then as a "function" in another.
  • Code examples are free of syntax and runtime errors.
  • Content-type specific standards are met.

Headers

  • All titles should be in Title Case.
  • Don’t include ending punctuation (except question marks).
  • Keep headers short, ideally 5 words or fewer.

Punctuation

  • Always use oxford commas.
  • Use em dashes ( — ) when making asides, en dashes ( – ) for spans of time or ranges, and normal dashes ( - ) to connected hyphenated words. Put spaces around your em dashes and en dashes ( — ).
  • Use exclamation points sparingly, default to periods.
  • Avoid semicolons (they often confuse readers).
  • Bulleted lists should be consistent with punctuation use: end a bullet with punctuation if it is a complete sentence, do not end in punctuation otherwise (except question marks).

When linking to other content items in Codecademy's catalog, make sure to use the full link to the course or Path landing page.

Use this link format:

  • https://www.codecademy.com/courses/learn-python-3

Do not use the link that uses the content item ID. Additionally, do not link to a content item where it exists in a path, unless it ONLY exists in a path.

Do NOT use these link formats:

  • https://www.codecademy.com/content-items/9873a1707395ea8bfc27d50a66208a2f/exercises/silce-a-string
  • https://www.codecademy.com/paths/computer-science/tracks/cspath-python-objects/modules/cspath-python-strings/lessons/introduction-to-strings/exercises/silce-a-string

Tone and Voice

A consistent tone and voice is used throughout content items. A few adjectives we use to describe our tone are: encouraging, confident, smart, fun, informal, approachable, expert, and optimistic. Some other things to note:

  • Don’t use profanity or curse words (even mild ones).
  • Avoid words and phrases that assume learners know the context like: "easy", "obvious", "of course", or "simply".

Introduction to New Material should use a "we" voice. In this way, Codecademy acts as a guide while including the learner in the process. For example, “If we wanted to define a new variable, we can use the following syntax...”.

Checks for understanding where learners are asked to perform a task (checkpoints, assessments, and projects) should use a "you" voice. For example, in an assessment or a project step, you may say, “You should create…“ or "Create..." in reference to what the learner specifically needs to do.

Pedagogy

Include motivation (the “why”)

Every Introduction to New Material and project should have an example, scenario, or reason to explain to the learner the “why” of the content. Why are they learning or doing this?

Use relatable analogies or metaphors

When writing content, consider using analogies or metaphors to help explain challenging concepts. Check out the running dishwasher analogy in the JavaScript Promises lesson for an example. While this isn't a perfect analogy, it connects a confusing, intangible concept to something relatable that many of our learners can understand.

Use diagrams or artwork to illustrate key concepts or processes

Make sure to follow Accessibility Best Practices in your artwork usage.

Explain all non-trivial code examples and diagrams

When including code examples or diagrams, explain them in detail. Err on the side of over-explaining even if the example seems trivial to you. This explanation can be an opportunity to reiterate key concepts and redefine key terms.

Focus on “need to have” content

All necessary Introduction to New Content should have a Learning Standard associated with it. If you decide to include content, but it doesn’t have an associated Learning Standard, you should create a new Learning Standard

If you feel strongly that some content will be essential to some learners but irrelevant to others, link to an appropriate course, Path or Docs page, include it in a "Next Steps" section, or remove it entirely.

Keep audience and prerequisites in mind

Our content will be taken by learners with different technical backgrounds and frames of reference. We should therefore aim for the lowest denominator within the content’s target audience.

When referencing code and/or concepts not directly addressed by your content, you should either:

  • Add the appropriate course or Path as a prerequisite for the container.
  • Remove it entirely (see Focus on "need to have" content section)
  • Teach the code/concept and create a Learning Standard for it.

Checks for understanding should be achievable

All checks for understanding (projects, assessments, etc.) should be reasonably achievable by all learners who complete the prerequisite content. Never introduce new concepts in a check for understanding.