Logo

Writing Effective Course Content

Writing Effective Course Content

In this chapter, you will learn how to create engaging and informative course content using Markdown. We will cover best practices for structuring your content, effectively using Markdown syntax, and writing clear and concise explanations.

Markdown Basics

Markdown is a lightweight markup language that you will use to write your course content. Here are some basic Markdown elements:

Headings

Use # for headings. More # symbols create smaller headings:

# Main Heading
## Subheading
### Smaller Subheading

Lists

For unordered lists, use - or *. For ordered lists, use numbers:

- Item 1
- Item 2

1. First Item
2. Second Item

Code Blocks

For inline code, use single backticks. For code blocks, use triple backticks:

Use `git commit` to commit your changes.

git add .
git commit -m "Your commit message"
git push origin main

[Link Text](URL)
![Alt Text](Image URL)

Best Practices for Writing Course Content

  1. Start with a short lead, not a formula: Avoid repeating the same sentence pattern such as “In this lesson, you will learn …” in every lesson. A short, concrete opening line is usually better.

  2. Use Goal selectively: Add ## Goal when the lesson has a clear operational task. Do not force it into every lesson.

  3. Use Clear, Concise Language: Explain concepts in simple terms and avoid technical jargon whenever possible.

  4. Organize Content into Sections: Use headings to divide your content into logical sections.

  5. Include Examples: Provide practical examples to illustrate concepts.

  6. Use Visual Elements: Include diagrams, screenshots, or other visuals to enhance understanding.

  7. Use Takeaway and Check deliberately:

    • ## Takeaway should condense the lesson into one rule, pattern, or mental model.
    • ## Check should be the final self-check block of the lesson.
    • Do not place another takeaway after the check.

  8. Use interactive questions for self-explanation: Reveal questions work well when learners should explain a concept in their own words or distinguish between two ideas.

  9. Make reveal answers real answers: Do not write placeholder prompts such as “Explain why …” or “Mention either …”. The revealed content should already be a short, complete model answer.

  10. Keep endings clean: If a lesson already ends with ## Check, avoid adding another full summary after it. Let the check feel like the end.

A practical default pattern looks like this:

# Lesson Title

One short opening line that frames the lesson.

## Goal

Use this only when learners are about to do something concrete.

## Do

Main explanation, examples, and steps.

## Takeaway

One compact rule, pattern, or summary.

## Check

Questions, reveal prompts, or a short self-check.

For conceptual lessons, you can omit ## Goal.
For capstone lessons, it can be useful to separate ## Verify your result from ## Check.

Using reveal questions well

Reveal questions are most useful when they help learners pause and explain something important:

  • distinguish setup from generated state
  • explain why one validation step matters
  • choose which file or command to inspect first

They are less useful when they only ask for isolated trivia.

Good reveal question:

{{< reveal question="Why should you inspect generated state instead of editing it?" >}}
Because the generated state records what the tool actually produced and helps you verify the result.
{{< /reveal >}}

Weak reveal question:

{{< reveal question="Why should you inspect generated state instead of editing it?" >}}
Explain why generated state is important.
{{< /reveal >}}

Exercise: Write a Lesson

  1. Choose one of the lesson files you created in the previous exercise.
  2. Write the content for this lesson, applying the Markdown syntax and the best practices discussed.
  3. Include at least one code block, a list, and an image in your lesson.
  4. Decide consciously whether your lesson needs ## Goal, ## Takeaway, and ## Check.
  5. If you use reveal questions, write full model answers for them.

In the next lesson, we will cover how to add and manage media resources for your course.