Skip to content

README.md

Latest commit

 

History

History
189 lines (154 loc) · 6.27 KB

README.md

File metadata and controls

189 lines (154 loc) · 6.27 KB

MarkSlide Go - Courses

Place all your course-definition files in the form of hiearchically organized yaml configuration-files into the courses/ directory. They will be used for the slide generator- and tool-scripts.

Glossary (lecturer shortnames)

  • SAM: Software Architecture and Middleware Technologies (/courses/bic4-sam)
  • SLM: Software Lifecycle Management (/courses/bic3-slm)
  • SWEN1: Software Engineering 1 LAB (/courses/bif3-swen1)
  • SWARC: Software Architecture (/courses/bif4-swarc)
  • SWEN2: Software Engineering 2 LAB (/courses/bif4-swen2)
  • SWEN3: Software Engineering 3 LAB (/courses/bif5-swen3)
  • DISYS: Distributed Systems (/courses/bwi4-disys)
  • GlobalMinor: Global Acting in IT (/courses/global-minor)
  • WebTechnologien: WebTechnologien (/courses/web1)
  • WebProgramming: WebProgramming (/courses/webp)

Generate Slides for a course

  • In create a sub-dir for each (e.g. moodle) course.
  • Inside the sub-directories there are YAML-files, containing the course-structure filled with the slides-config per topic.

To generate all the slides for a moodle-course move inside the specific course-directory, and execute the following command:

$ python3 generate_course.py <coursefile>.yml

The output will be stored in the corresponding output/ subdirectory.

Course Root Files (CIS.md)

Every course root folder should contain a CIS.md file with the course meta information. CIS.md is the source of truth for course-level metadata and teaching intent.

Each CIS.md should include these sections in German and English:

  • Kurzbeschreibung / Course Description
  • Methodik / Teaching Methods
  • Lernergebnisse / Learning Outcomes
  • Lehrinhalte / Course Contents
  • Literatur / Recommended Reading and Material
  • and additional course-specific sections where required

Notes for Lernergebnisse / Learning Outcomes:

  • Use a bullet list.
  • Map each learning outcome item to Bloom's taxonomy.

Operational rule:

  • During content generation and updates, always consider the metadata defined in the corresponding course CIS.md.
  • Do not modify CIS.md unless a lecturer explicitly requests that change.
  • When content changes make CIS.md documentation potentially inconsistent, report the mismatch to the lecturer.

Course Root Files (course.md)

Every course root folder should contain a course.md file with the information that is published into the generated Moodle course.

course.md should include at least these sections:

  • Assessment
  • Assessment Criteria

Assessment must include these subsections:

  • Grading Parts
  • Marking System
  • First Retake
  • Second Retake (Panel exam)

Moodle Topic Folder Semantics

Subfolders below a course root folder have a fixed meaning for Moodle topic generation:

  • SS-A, SS-B, SS-C, ... contain the material for Self-Study topics (Self-Study A, Self-Study B, ...)
  • Class-1, Class-2, ... contain the material for Class topics (Class 1, Class 2, ...)

Notes:

  • Some SS-? or Class-? folders may be missing.
  • Missing folders mean no material is generated yet for those topics.

Markdown Topic Metadata (inside content files)

Markdown files may contain these topic/course metadata keys:

  • section_number: Number of the Moodle topic the document applies to
  • section_name: Name of the Moodle topic the document applies to
  • course_name: Name of the Moodle course (same for all documents in a course)
  • source_shortname: Shortname of the Moodle course (same for all documents in a course)

Remark:

  • This metadata model was added recently; some files may not contain all keys yet.

YAML file format

Finde here a JSON Schema representation of the YAML file format:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "course-title": {
      "type": "string",
      "description": "Title of the course"
    },
    "course": {
      "type": "string",
      "description": "Short course code"
    },
    "program": {
      "type": "string",
      "description": "Program or degree abbreviation"
    },
    "version": {
      "type": "string",
      "description": "Version of the configuration file"
    },
    "topics": {
      "type": "array",
      "description": "List of topics in the course",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Topic name or identifier"
          },
          "title": {
            "type": "string",
            "description": "Title of the topic"
          },
          "slides": {
            "type": "array",
            "description": "List of slides for the topic",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Title of the slide"
                },
                "source": {
                  "type": ["string", "null"],
                  "description": "Source file for the slide (single file)"
                },
                "sources": {
                  "type": ["array", "null"],
                  "description": "Source files for the slide (multiple files)",
                  "items": {
                    "type": "string"
                  }
                },
                "target": {
                  "type": "string",
                  "description": "Output target file for the slide. The following suffixes are supported: .html, .pdf and .pptx"
                },
                "options": {
                  "type": ["string", "null"],
                  "description": "Optional settings for the slide, one of: --zip, --scorm"
                },
                "questions": {
                  "type": ["integer", "null"],
                  "description": "Number of questions to generate associated with the slide (requires OpenAI key in .env file)"
                }
              },
              "required": ["title", "target"],
              "oneOf": [
                {
                  "required": ["source"]
                },
                {
                  "required": ["sources"]
                }
              ]
            }
          }
        },
        "required": ["name", "title", "slides"]
      }
    }
  },
  "required": ["course-title", "course", "program", "version", "topics"]
}