Skip to content

Latest commit

 

History

History
76 lines (65 loc) · 4.35 KB

markdown_style.md

File metadata and controls

76 lines (65 loc) · 4.35 KB
Raw

General style for Markdown Files

General style

  • File title is in Title Case, starts with a single digit, and uses underscores to separate between words. We follow APA Style Guide for capitalization: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case. This means you should not capitalize minor words.
  • Notebook title is H1 and includes Workshop Name: Subtitle
  • Keep the scaffolding at the top and bottom of the template notebook intact
  • Use H1 for main headers that are referred to in the "Sections" section.
  • All headers are in Title Case. We follow APA Style Guide: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case. This means you should not capitalize minor words.
  • Use H2 for subsections. These do not need to be linked to in the "Sections" section at the top of the notebook.
  • Use H3 headers for subsubsections. Don't go lower than H3 if you can avoid it.
  • Use emoji specified in the "Icons Used in This Notebook" section
  • Keep narrative text limited!
  • Avoid discussion of edge cases or caveats.
  • Use colloquial language and minimal jargon; if you need it, explain it.
  • Use boldface to highlight key concepts and important terms, but use it sparingly.
  • Don't use italics.
  • Use en-dash for lists.
  • Use code font for anything in code like variables, functions, and packages.
  • Use code font for menu items and UX pathways (like Restart Kernel or Kernel-> Restart)
  • Use code font for data frame rows/columns.
  • When discussing functions, include the trailing parentheses (e.g. print()).
  • When discussing methods, include the dot (e.g. .sum()).
  • Consistently use emoji for relevant sections. See below for some examples.

Learning Objectives

  • At least 3, max 6 per markdown file.
  • Keep them short – one line each.
  • Use learning objective verbs. E.g. "Distinguish between the main data types in Python."

Challenge 🥊

  • Challenges are typically formatted as H2 / subsection (##).
  • Challenges use the 🥊 Boxing Glove emoji in the header.
  • Try to have at least one exercise every 20 minutes of instruction.
  • Challenges have names, and are numbered. You should reference those names in a Solutions file.

Tip 💡

  • Tips can be formatted as subsection (##) when they're more substantial.
  • Tips can be used without header when they are less substantial.
  • Tips use the 💡 Electric Light Bulb Emoji in the header / at the start of the line, followed by boldface Tip:, followed by the tip.
  • Tips are not numbered.
  • Keep them short and to the point.

Question 🔔

  • Questions are used without header.
  • Questions use the 🔔 Bell Emoji at the start of the line, followed by boldface Question:, followed by the question.
  • Questions are short queries about code or concepts.
  • Questions do not require participants to enter code.
  • Questions can be used as attention checks, and discussed during the workshop.

Warning ⚠️

  • Warnings are used without header.
  • Warnings use the ⚠️ Warning Sign Emoji at the start of the line, followed by boldface Warning:, followed by the warning message.
  • Warnings act as short reminders to participants of common mistakes and errors.

Poll 📝

  • Polls refer to Zoom polls, which can be used as a form of formative assessment.
  • Talk to D-Lab staff if you want to create Zoom polls before adding them in the notebook.
  • Polls use the 📝 memo enoji at the start of the line, followed by boldface Poll, followed by the name of the poll.
  • Polls are named with the format {workshop name}{workshop part - poll number}
  • make sure to check if they are activated by clicking "Polls/Quizzes" in Zoom.
  • Polls are used without header.

Demo

  • Demos can be used at the end of a notebook to show / highlight some advanced functionalities outside the scope of the workshop.
  • Demos use the 🎬 Clapper Board Emoji at the start of the header.
  • Demos are written as main sections (#) that are linked to in the "Sections" section.
  • Demos can used once per notebook.
  • Demos can be used to enthuse participants, and to point them to relevant other D-Lab workshops.
  • Demos are meant to be short: 5-10 mins max.

Key Points

  • Key Points are at the bottom of the notebook.
  • Key Points recap the most important concepts and ideas covered.
  • Use at least 3 and at most 8 Key Points.