Logo

Writing Effective Course Content

Creating 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. Name headings after content: A heading says what the section contains (“Setup files”, “Why the distinction matters”). Avoid schema headings such as “Goal” or “Do”.

  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. Close with a rule, then Check: Condense the lesson into one compact rule or short list right before ## Check, without its own heading. ## Check is the final block of the lesson.

  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. Frame sections, not every lesson: Put {{< objectives >}} at the start of a section’s first lesson and {{< keypoints >}} at the end of its last lesson. Only lessons of 10 minutes or more get their own pair.

Voice and language

Address learners formally (“you” in English, “Sie” in German) and keep the tone matter-of-fact. Instructions the learner must execute are imperative (“Run:”); everything else describes. Code, CLI output, file names, and the ## Check heading stay in English in both languages. All other headings are written in the lesson’s language.

German lessons follow three additional rules: open with a descriptive sentence instead of a translated imperative, use “Sie” sparingly, and write task lists in infinitive style (“das Projektverzeichnis anlegen”). The full conventions and the terminology table are in the repository under docs/course-writing-guide.md .

A practical default pattern looks like this:

# Lesson title

One or two sentences that frame the lesson.

## Heading named after the content

Explanation, examples, and steps.

## Common failures

{{< troubleshoot problem="A typical mistake" >}}
What to do instead.
{{< /troubleshoot >}}

The compact rule of this lesson, as a short paragraph or list.

## Check

{{< reveal question="A question learners should now be able to answer" >}}
A complete model answer.
{{< /reveal >}}

The first lesson of a section opens with {{< objectives >}} right after the lead; the last lesson of a section ends with {{< keypoints >}} after its ## Check. For capstone lessons, it can be useful to separate a “Verify your result” heading 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 where your lesson sits in its section and whether it opens with objectives or closes with key points.
  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.

Optional feedback