Skip to content

Introduction

Estimated time to read: 13 minutes

What you'll Learn

In this workshop, you'll master the art of creating exceptional workshop documentation. This comprehensive guide covers everything from understanding your audience and structuring content to leveraging modern documentation tools like MkDocs and AI-assisted writing. By the end of this workshop, you'll have the practical skills and knowledge to produce high-quality, engaging documentation that enhances the learning experience for all participants.

Workshop Goals

This workshop aims to establish best practices for workshop documentation that deliver:

  • Consistent learner experience: Standardized structure and formatting that participants can rely on
  • Clear learning outcomes: Well-defined objectives that help learners understand what they'll achieve
  • Engaging content: Interactive elements and practical exercises that maintain participant attention
  • Accessible materials: Documentation that works for diverse audiences and learning styles
  • Sustainable processes: Workflows that make creating and maintaining workshop content efficient

Welcome to Workshop Documentation Best Practices

Creating effective workshop documentation is both an art and a science. Great workshop materials don't just convey information—they guide learners through a transformative experience, building skills and confidence step by step.

Whether you're creating technical training, educational workshops, or professional development content, the principles and tools you'll learn here will help you craft materials that truly serve your audience's needs.

Workshop Structure Overview

This workshop is organized into six hands-on labs, each focusing on a key aspect of workshop documentation:

Lab 1: Understanding Your Audience - Learn to identify and analyze your target learners, adapting your content to meet their specific needs and skill levels.

Lab 2: Workshop Structure & Content Design - Master the fundamental principles of organizing workshop content, creating clear learning paths, and maintaining engagement.

Lab 3: Setting up MkDocs Documentation - Get hands-on experience with MkDocs, the modern documentation framework that powers great workshop materials.

Lab 4: Advanced MkDocs Features - Explore powerful features like admonitions, sticky tabs, and content includes to create rich, interactive documentation.

Lab 5: AI-Assisted Content Creation - Discover how to leverage AI tools to enhance your writing process, improve clarity, and create more effective content.

Lab 6: Publishing and Deployment - Learn to deploy your documentation using GitHub Pages and establish workflows for maintaining and updating your materials.

Each lab builds upon the previous ones, culminating in a complete understanding of the workshop documentation lifecycle.

Getting Started with This Workshop

Ready to begin your journey toward creating exceptional workshop documentation? Here's how to get started:

Prerequisites

  • Basic familiarity with Markdown syntax
  • A GitHub account for accessing repositories and deployment
  • A text editor or IDE (VS Code recommended)
  • Python 3.7+ installed on your system

Workshop Setup

Clone the workshop repository:

Bash
1
2
git clone https://github.com/microsoft/ai-tour-26-workshop-docs-architecture
cd ai-tour-26-workshop-docs-architecture/docs

Install the required dependencies:

Bash
1
pip install -r requirements.txt

Start the local development server:

Bash
1
mkdocs serve

Once running, you can preview your documentation at http://127.0.0.1:8000.

Learning Path

Each lab in this workshop builds upon the previous one, so we recommend completing them in order. However, if you're already familiar with certain concepts, feel free to focus on the areas most relevant to your needs.

The workshop is designed to be completed in about 3-4 hours, with each lab taking approximately 30-45 minutes to complete.

Interactive Learning

This workshop emphasizes hands-on practice. You'll be creating, modifying, and publishing actual documentation as you progress through each lab.

Let's begin with Lab 1, where you'll learn to understand and analyze your audience—the foundation of all effective workshop documentation.

Getting Started with MkDocs

  • Install requirements: The requirements.txt file for MkDocs is in the docs folder. Install dependencies with:

    Bash
    1
    pip install -r docs/requirements.txt

  • Run MkDocs locally:

    Bash
    1
    cd docs && mkdocs serve

Once running, you can live preview your documentation by clicking the link shown in your terminal (usually http://127.0.0.1:8000 or similar).

Understand the MkDocs Structure

MkDocs organizes documentation into a specific structure. Familiarize yourself with the following key components:

  • mkdocs.yml: The main configuration file for your MkDocs project. It defines the site structure, theme, and plugins.
  • docs/: The directory containing your Markdown files. Each Markdown file corresponds to a page in your documentation.

  • docs/docs/en/: is the folder for English content and should remain the default language folder.

    When adding a new language, create a corresponding folder using the appropriate ISO 639-1 code—for example, docs/docs/es/ for Spanish or docs/docs/fr/ for French.

    This structure cleanly separates languages, making translations easier to manage. It also ensures that relative paths to assets (like images) remain consistent across all languages, so translations work without needing path updates.

  • includes/: A folder for reusable content snippets that can be included in multiple pages.

  • requirements.txt: A file listing the Python packages required for your MkDocs project.

Don't use Heading level 1

MkDocs automatically generates the main title from the mkdocs.yml file, so avoid using Heading level 1 (#) in your Markdown files. This avoids TOC and Doc headings from getting out of sync. Use Heading level 2 (##) for main sections and Heading level 3 (###) for subsections.

Time to Read Plugin

The Time to Read plugin estimates the reading time for your documentation pages. It provides a quick way for users to gauge the length of content before diving in.

Using MkDocs Admonitions (Tips, Warnings, Info)

You can use MkDocs admonition to highlight important information, tips, warnings, and more in your documentation. Try and be consistent with your use of admonitions. Here are some commonly used admonition:

Raw Markdown:

Markdown
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
!!! tip
    This is a tip annotation.

!!! warning
    This is a warning annotation.

!!! info
    This is an info annotation.

!!! note
    This is a note annotation.

!!! danger
    This is a danger annotation.

!!! success
    This is a success annotation.

!!! question
    This is a question annotation.

How it Renders:

Tip

This is a tip annotation.

Warning

This is a warning annotation.

Info

This is an info annotation.

Note

This is a note annotation.

Danger

This is a danger annotation.

Success

This is a success annotation.

Question

This is a question annotation.

Tricks for Sticky Tabs

Use sticky tabs to show code examples in multiple languages. Example:

Raw Markdown:

Markdown
1
2
3
4
5
6
7
8
9
=== "Python"
    ```python
    print("Hello, AI Tour 26!")
    ```

=== "C#"
    ```csharp
    Console.WriteLine("Hello, AI Tour 26!");
    ```

How it Renders:

Python
1
print("Hello, AI Tour 26!")
C#
1
Console.WriteLine("Hello, AI Tour 26!");

You notice that sticky tabs will not only work on the current page, but also across the entire site. This means that if you have a Python code example in one lab, it will be available as a sticky tab in all other labs where you include it.

Python
1
print("Hello, AI Tour 26!")
C#
1
Console.WriteLine("Hello, AI Tour 26!");

Splitting Content with 'includes'

You can split out reusable content using the includes folder. For example to include a common introduction for self-guided learners:

{% include-markdown "includes/en/introduction-self-guided.md" %}

This will include the content from docs/docs/includes/en/introduction-self-guided.md into your page.

Explore the docs/docs/includes folder for more examples.

Using LLMs to Help with Content Creation

Large Language Models (LLMs) like GitHub Copilot or ChatGPT can be valuable tools for improving your documentation. Here are some example prompts you can use to enhance your content:

Useful Prompts for Document Content Creators:

  • Rewrite to be concise and clear.
  • Look for inconsistencies in terminology and suggest standardization.
  • Summarize this section for a beginner audience.
  • Suggest a more engaging introduction for this lab.
  • Check this text for grammar and spelling errors.
  • Convert this list into a step-by-step guide.
  • Add a practical example to this explanation.
  • Rephrase this to be more formal/informal.
  • Highlight the key takeaways from this section.
  • Suggest improvements for accessibility and inclusivity.

Experiment with these prompts to make your documentation more effective and user-friendly.

Deploying to GitHub Pages

You can easily publish your documentation using GitHub Pages. Here are the steps:

1. Add a GitHub Actions Workflow

Create a file at .github/workflows/gh-pages.yml in your repository with the following content:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
name: Deploy MkDocs to GitHub Pages
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    env:
      CONFIG_FILE: docs/mkdocs.yml
      REQUIREMENTS: docs/requirements.txt
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install "mkdocs>=1.6.1,<1.7.0" "mkdocs-glightbox>=0.4.0,<0.5.0" "mkdocs-material>=9.6.15,<10.0.0" "mkdocs-include-markdown-plugin>=7.1.6,<8.0.0" "mkdocs-static-i18n==1.3.0" "mkdocs-timetoread-plugin>=0.0.4,<0.1.0"
      - run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml

2. Enable GitHub Pages

Go to your repository settings, find the Pages section, and set the source to gh-pages branch. After your workflow runs, your site will be published at the provided URL.

For more details, see the MkDocs GitHub Pages documentation.

Language Translations

  1. From VS VCode and GitHub Copilot in Agent mode.

  2. Add Context to Copilot

  3. mkdocs.yml

  4. docs folder

  5. The agent will translate the files and update the mkdocs.yml file with the new language settings in batches. You'll need to ask the agent to continue until all files are translated.

  6. Add the following instructions to the agent (note the agent will prompt you as it progresses, just type continue to keep it going until all files are translated):

    Markdown
      1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
    ## Role  
You are a professional technical writer and translator.

## Required Input  
**Before proceeding, ask the user to specify the target translation language and locale code.**  
Examples:
- Spanish (`es`)
- French (`fr`)
- Brazilian Portuguese (`pt-BR`)
- Korean (`ko`)

Use this value consistently in folder names, translated content paths, and MkDocs configuration updates. Once confirmed, proceed with the instructions below.

---

## Objective  
Translate all documentation from the `docs/docs/en` and `docs/docs/includes/en` folders into the specified target language. Preserve the original folder structure and all Markdown formatting.

---

## File Listing and Translation Order

- Begin by listing all files and subdirectories under `docs/docs/en`.

- Then list all files and subdirectories under `docs/docs/includes/en`.

- Translate **every file** in the list **one by one** in the order shown.  
  Do not skip, reorder, or stop after a fixed number of files.

- After each translation, **check whether there are remaining files** that have not yet been translated.  
  If there are, **continue automatically** with the next file.

- Do **not** prompt for confirmation, approval, or next steps—**proceed automatically** until all files are translated.

- Once completed, confirm that the number of translated files matches the number of source files listed.  
  If any files remain unprocessed, resume from where you left off.

---

## Folder Structure and Output

- Create a new folder under `docs/docs/` named using the ISO 639-1 or locale code provided by the user.  
  Examples:  
  - `es` for Spanish  
  - `fr` for French  
  - `pt-BR` for Brazilian Portuguese

- Mirror the exact folder and file structure from the original `en` directories.

- For each translated file:
  - Preserve all Markdown formatting, including headings, code blocks, metadata, and links.
  - Maintain the original filename.
  - Do **not** wrap the translated content in Markdown code blocks.
  - Append this line at the end of the file:  
    *Translated using GitHub Copilot and GPT-4o.*
  - Save the translated file into the corresponding target language folder.

---

## Include Path Updates

- Update include references in files to reflect the new locale.  
  Example:  
  `includes/en/introduction-event.md` → `includes/es/introduction-event.md`  
  Replace `es` with the actual locale code provided by the user.

---

## MkDocs Configuration Update

- Modify the `mkdocs.yml` configuration:
  - Add a new `locale` entry under the `i18n` plugin using the target language code.
  - Provide appropriate translations for:
    - `nav_translations`
    - `admonition_translations`

---

## Translation Rules

- Use accurate, clear, and technically appropriate translations.
- Always use computer industry-standard terminology.  
  Example: prefer “Stack Tecnológica” over “Pila Tecnológica”.

**Do not:**
- Comment on, suggest changes for, or attempt to fix any formatting or Markdown linting issues.  
  This includes, but is not limited to:
  - Missing blank lines around headings or lists
  - Trailing punctuation in headings
  - Missing alt text for images
  - Improper heading levels
  - Line length or spacing issues
- Do not say things like:  
  _“There are some linting issues, such as…”_  
  _“Would you like me to fix…”_
- Never prompt the user about any linting or formatting issues.
- Do not wait for confirmation before continuing.
- Do not wrap the translated content or file in Markdown code blocks.

---

## Translating Includes (`docs/docs/includes/en`)

- Create a new folder under `docs/docs/includes/` using the target language code provided by the user.
- Translate each file using the same rules as above.
- Maintain the same file and folder structure in the translated output.
- Save each translated file in the appropriate target language folder.