This document is a reference for writing and formatting the markdown portion of EWB exercises. There are separate documents about writing and formatting code blocks and hints, and testthat tests.

• TL;DR – Quick Code Block Reference
• Tone
• Formatting

Use these conventions across all Epi-Workbench coding exercises, labs, and culminating exercises:

• Use a friendly, supportive, and concise tone.
• Write as if talking directly to a curious but cautious learner.
• Avoid overly academic, robotic, or formal language.
• Use active voice and present tense whenever possible.
• Avoid using "you", "you're", or "you'll" unless explicitly approved.

• Use # for the Overview section, Task headers, and Question headers.
• Add 1 line break before each header and before/after each code block.

• Use backticks for inline code: filter()
• Use fenced code chunks ({r} ...) for executable code.
• Wrap function names with backticks and include parentheses: mean()
• Wrap package names with backticks: ggplot2

• Bold glossary-worthy terms (e.g., global environment)
• Italicize for emphasis only—not for glossary terms
• Do not combine bold, italics, underline, or caps for the same word

• Use backticks for file paths, file names, dataset names, and variable names: data/summary.csv, EWB_Style_Guide.qmd
• Use standard hyperlink syntax only for links

• Capitalize software names: Microsoft Word, RStudio, GitHub

• Wrap clickable UI elements in backticks: Insert, Format Cells

• Use standard Markdown syntax—[descriptive text](https://example.com) — with clear, meaningful anchor text (e.g., “CDC Data Portal”), not bare URLs or generic phrases such as “click here.” Always include the full https:// URL so the link remains portable across platforms.

Stay consistent across lessons to ensure a polished, learner-friendly experience.

Top

We want all EWB exercises to have a friendly, collaborative tone—one that says, "we're in this together." To support that, we will use first person plural language ("we" and "us") instead of first person singular ("I") or second person ("you") in most instances.

✅ Do this:\

• "Remember, it's considered a best practice to load all the packages that our R code file will use at the top of the file." - "We don't need to change anything about the code." - "We used the tibble() function to create our data frame."

❌ Do not do this:\

• "Remember, it's considered a best practice to load all the packages that your R code file will use up at the top of the file." - "You don't need to change anything about the code." - "I used the tibble() function to create my data frame."

That said, there may be times when second person language is necessary for clarity, or when first person singular and second person are used in a direct quote. For example: - "If you are one of those people, we empathize with you." - "Here, we assigned each participant a number representing the category they selected as their answer to the question, 'Do you have a doctor who gives you your usual medical care?'" (direct quote)

Top

Use the following conventions to format keywords, concepts, code snippets, and other important elements in Epi-Workbench written lessons, coding exercises, lab exercises, and course culminating exercises. All lessons are written using markdown syntax.

Use consistent heading levels to clearly organize content and ensure clean rendering on the platform.

• Use level-one headings (#) for the following:
  • The Overview section at the top of each lesson.
  • Each Task in coding or lab exercises (e.g., # Task 1).
  • Each Question in culminating exercises or labs (e.g., # Question 1).
• Add 1 line break before all headings.
• Add 1 line break before and at least 1 line break after each code chunk.

Use these conventions to format code snippets, package references, and function names in R.

• Wrap inline code in single backticks: code here.
• Wrap function names in single backticks and include empty parentheses: filter().
• Wrap package names in single backticks: ggplot2.
• Place executable code in fenced R code blocks ({r} ...).

✅ Do this: - install.packages("dplyr") - "...the dplyr package..." - "Use the tibble() function to create a data frame..."

❌ Do not do this: - install.packages("dplyr") - "...the dplyr package..." - "The tibble function..."

Use bold text to emphasize glossary-worthy terms and concepts.\

• Bold terms that would merit inclusion in a glossary: global environment, logical operator.

✅ Do this:
"You should notice the names vector appear in your global environment."

❌ Do not do this: - global environment - global environment (plain text)

Use italics for emphasis or to highlight terms that are important but not glossary-worthy.\

• Follow standard English grammar rules for italics. - Do not combine italics with bold, underline, or all caps.

✅ Do this:
"...adding objects to our global environment is not the same as saving them..."

❌ Do not do this: - "...NOT/not/not..."

Wrap file paths in single backticks to distinguish them from surrounding text.

✅ Do this:
Documents/General/SOPs/02 Style Guide.docx

❌ Do not do this:
“Documents/General/SOPs/02 Style Guide.docx”

File and folder names are treated as short paths and follow the same formatting rules as file paths.\

• Always wrap in backticks unless part of a hyperlink. - This includes dataset names and variable names.

✅ Do this:\

• lab_module_name.qmd - "Please download chocolate study 1.xls"

❌ Do not do this: - lab_module_name.qmd - "Please download chocolate study 1.xls"

Capitalize names of applications and software tools.

✅ Do this:
Microsoft Outlook, Microsoft Planner, GitHub, RStudio

❌ Do not do this:
microsoft outlook, planner, github, rstudio

Clickable actions in software should be styled like code since they represent interface-driven logic.\

• Use single backticks for UI labels: buttons, tabs, fields.

✅ Do this:
Click on the Insert tab...
Select Format Cells from the context menu...

❌ Do not do this:
Click on the Insert tab, the Insert tab, or Insert tab

Top