Creating and editing course files

About courses

Previously, Experience League courses were created in Airtable. These courses are available only through sign-in. As a result, courses were not available in either internal or external search. We’re working on improving courses in two key ways:

  • Make courses available to customers via search.
  • Create and edit courses in Markdown files rather than in Airtable.

The courses.en repo is now the source of truth for courses. Each markdown file in this repo is the source of both the stub article that appears in search and the course that the stub topic links to.

course illustration

Example files for the “Analytics Fundamentals for Leaders” course:

Create a New Course

  1. Use these template files to get started with creating a course:

    • The template-example.md template includes comments with examples. Feel free to copy and edit this template or use it as a reference while editing the clean template. If you edit this template, please delete the comments before pushing the files through.
    • The template-clean.md doesn’t have any comments.

    template

  2. Determine the course-id format to be used for the course-id value and filenames.

  3. Copy one of the template files into the courses subdirectory and rename it based on the course-id you’ll be using.

    Example: experiencemanager-d-1-2022.3.formscs.md

    See the next section for an example.

  4. In the new file, specify values for all the required metadata fields. See the template-example.md template for details.

  5. In the main section of the markdown article, edit the # title text, the description text, and add bullet points to the “What you’ll learn” section.

  6. Follow similar steps to create additional course files. Example:

    • experiencemanager-d-1-2022-3-formscs.md
    • experiencemanager-d-2-2022-3-formscs.md
    • experiencemanager-d-3-2022-3-formscs.md
    • experiencemanager-d-4-2022-3-formscs.md
  7. Save the files in a git branch. The branch name should have the same name as the KT or JIRA number.

  8. Create a pull request to propose merging the PR into main. Include the necessary reviewers.

    We’re still working on adding validation rules for courses and working out the kinks.

  9. If validation succeeds and the PR is approved, ask Jason to push merge the PR.

    The system processes the course files and adds required metadata and content into the course files, preparing them for preview and publish.

  10. Check the course content on stage.

  11. When ready, edit the publish: false metadata in the course files to publish: true, and submit a new pull request.

Course metadata

https://wiki.corp.adobe.com/display/ExpLeague/Course+Syntax+and+Validation

title: REQUIRED (all) - Example: “Learn to use Forms as a Cloud Service document generation micro-services”

description: REQUIRED (all) - Example: “Merge data with xdp template by invoking the HTTP endpoints of Forms CS.”

solution: REQUIRED (all) - Must match solution.yml value

role: REQUIRED (all) - Must match role.yml value

level: REQUIRED (all) - Must match level.yml value

course-id: REQUIRED (all) - Use Solution-RoleLetter-SequenceNumber-Year.Revision.Series; Example: “ExperienceManager-D-1-2022.3.formscs; For RoleLetter, use U for user, D for developer, A for admin, or L for leader”

course-thumbnail: REQUIRED (all) - Example: “/www/img/thumb/learn-to-use-aem-forms-as-a-cloud-service’s-document-generation-microservices.png”

course-title: REQUIRED (all) - Example: “Learn to use Forms as a Cloud Service document generation micro-services”

course-description: REQUIRED (all) - Example: “Merge data with XDP templates by invoking the HTTP endpoints of AEM Forms as a Cloud Service.”

course-path-title: REQUIRED (first lesson only) - Example: “Learn to use Forms as a Cloud Service document generation micro-services”

course-path-description: REQUIRED (first lesson only) - Example: “Merge data with xdp template by invoking the HTTP endpoints of Forms as a Cloud Service.”

course-url: REQUIRED (all) - Example: “https://experienceleague.adobe.com/?recommended=$course-id#dashboard/learning”

course-length: REQUIRED (all) - Example: “1 hour”

course-next: REQUIRED (all but last lesson) - ExperienceManager-D-2-2022.3.formscs

course-survey-url: NOT REQUIRED, not used

community-url: NOT REQUIRED - Example: “https://experienceleaguecommunities.adobe.com/t5/adobe-experience-manager-forms/course-discussion-learn-to-use-aem-forms-as-a-cloud-service-s/m-p/437814#m2130”

community-manager: NOT REQUIRED - Girish Bedekar

community-manager-picture: NOT REQUIRED - Example: “https://experienceleaguecommunities.adobe.com/t5/image/serverpage/avatar-name/vampire/avatar-theme/candy/avatar-collection/monsters/avatar-display-size/profile/version/2?xdesc=1.0”

course-hide: false

award-title: REQUIRED (last only)

award-description: REQUIRED (last only)

archived: false

publish: false # Must be FALSE during start phase

hide: false

menu: REQUIRED (first guide only) - Example: Manage Forms

training: NOT REQUIRED

meta

meta:
  - title: Length
    description: REQUIRED - Example: "2 minutes"
  - title: Audience
    description: REQUIRED - Example: "Developer"

guides

guides:
  - guide-title: REQUIRED - Example: "Learn to use AEM Forms as a Cloud Service's document generation microservices"
    step-title: REQUIRED - Example: "Document generation using the communication API"
    title: REQUIRED - Example: "Document generation using the communication API"
    description: REQUIRED - Example: "Merge data with xdp template by invoking the HTTP endpoints of Forms CS"
    qualifier-id: 0 # REQUIRED (to be deprecated) - Example: "52540"
    thumbnail: REQUIRED - Example: "/www/img/thumb/334859.jpeg"
    url: REQUIRED - Example: "https://video.tv.adobe.com/v/334859/?quality=12&learn=on"

steps

steps:
  - title: REQUIRED - Example: "Learn to use AEM Forms as a Cloud Service's document generation microservices"
    description: REQUIRED - Example: "Merge data with XDP templates by invoking the HTTP endpoints of AEM Forms as a Cloud Service."
    label: REQUIRED - Example: "Get Started"
    guide: REQUIRED - Example: "52540"

Example of completed new course

At this stage, it’s easier to learn by example and track the progression of commits in a pull request. Let’s use this one:

https://git.corp.adobe.com/AdobeDocs/courses.en/pull/12

The branch name has the same name as the KT or JIRA number.

The course-id (case-sensitive) looks like this:

Solution-RoleLetter-SequenceNumber-Year.Revision.Series

ExperienceManager-D-1-2022.3.formscs

This example is an Experience Manager course for developers. This is the first course in a sequence. Created in 2022, third version, with formscs as the series name. The last 3 items (2022.3.formscs) help ensure course ID uniqueness.

  • Solution name (as specified in solution.yml without spaces)
  • Role: U = user, A = admin, L = leader, D = developer
  • Course number (1, 2, 3, 4, etc.)
  • Everything after the course number must be unique.

The course in this example consists of 4 files (lowercase) with corresponding course-id values (mixed case):

  • experiencemanager-d-1-2022-3-formscs.md
  • experiencemanager-d-2-2022-3-formscs.md
  • experiencemanager-d-3-2022-3-formscs.md
  • experiencemanager-d-4-2022-3-formscs.md

The first file represents the course that users see when they click View Course. The other three are subsequent parts of the course.

-We need screen shots to point out where metadata is used in courses-

Solution values

Here are the things you should know about solution when tagging courses:

  • AEM and Campaign have sub-solutions (which you can see in search).
  • For general AEM courses, use solution: Experience Manager. For specific AEM courses, use solution: Experience Manager, <subsolution> (valid values include Experience Manager Sites, Experience Manager Assets, Experience Manager Screens, Experience Manager Forms, and Experience Manager XML Documentation). Do not use the AEM version values at this time.
  • For Campaign, use solution: Campaign, <subsolution>. Valid values are Campaign Classic v7, Campaign v8, and Campaign Standard.
  • Platform no longer includes subsolutions. For general platform courses, use solution: Experience Platform. For specific platform products, use metadata like solution: Intelligent Services or solution: Data Collection.
  • Deprecated solution values that we can’t yet get rid of but shouldn’t be used because they’re not filters: Acrobat DC, Adobe Commerce, Adobe Sign, Campaign Classic, Magento, Magento Commerce Cloud. For now, don’t use the AEM version tags (6.4, 6.5, CS), until we sort out some issues.

Edit an Existing Course

We need more info.

When you edit the page, make sure that all metadata is filled out. However, do not edit course-id, course-url, or exl-id; the values for these fields is system-generated.

List of validation rules for Matt

Validation in progress.

Strings

  • All title and description metadata cannot be multiple paragraphs. No HTML.

ENUM

  • Same

Requests

Add links to jira tickets

https://jira.corp.adobe.com/browse/UGP-5881

On this page