Instructional design review

This page contains:

The Microlearning Specialist (MLS) performs the first review of the module document, the instructional design (ID) review. Here are checks you, as the MLS, should perform.

Check the module against the Design doc

The module content should align to the Design doc in content, length, and learning objectives. Refer to the design document (design doc) and the module to check that the module follows the information in the design doc. If not, use a comment to call this out to the SME Writer (SME). You might also contact the Project Manager (PjM) and the SME about the change.

Note: Design changes are allowed but must be reflected in the design document. If the change is agreed to by the PjM and SME, you’ll need to update the design document to reflect the change.

Refer to the approved Design doc and review the module to check:

  • Each unit’s title to be sure all units in the Design doc are present in the module, and in the same order.

  • The estimated time for each unit. The time should be the same as the Design doc, or should be no more than 10-12 minutes for each unit, with a total of between 30 and 60 minutes for the entire modules. The estimated time will be entered in the YML file associated with the unit.

  • The content of each unit against the learning objectives in the Design doc to make sure they’re all covered.

    Note: Sometimes unit content changes order or content is moved from one unit to another to accommodate flow. Ask the SME if you have questions or to clarify the content. Keep in mind that the client signed off on the Design doc, so the SME can’t omit or add content without approval. Ask your Project Manager (PjM) for help with this.

Review the module for adherence to Microsoft Learn Contributor Guide

Important: In addition to these materials, you should familiarize yourself with the information and requirements found in the Microsoft Learn Contributor Guide.

Tip: Download the PDF version of the Microsoft Learn Contributor Guide if you can’t access the online guide using links on this and other pages. This is usually caused because of outdated or missing v-dash credentials.

The module content should align to the guidance in the [Microsoft Learn Contributor Guide]. Review the module to check for the following components.

Module structure

The module structure should have been addressed in the Design doc, but you should still double-check that the module:

  • Starts with an Introduction unit.

  • Ends with a Summary unit.

  • Has at least one knowledge check, one being the penultimate unit.

File names

For learning content units, check that each unit’s filename follows the Microsoft Learn guidelines:

  • Filenames must be lower case, avoid abbreviations, be no longer than 80 characters, and use hyphens, never underscores.

  • Filename should approximate the unit’s title but don’t need to be an exact match.

    Note: Unit titles are not included in the unit. The file name that appears in the published unit is the title in the metadata of the associated YML file.

Specific unit content

There is specific guidance for introduction, knowledge check, exercise, and summary units. For example, the introduction unit must contain a scenario that should be used throughout the module in the introduction paragraph of all learning content units.

Important: Please read and refer to Module content overview for more information about the content of specific units. Also refer to the Microlearning combined template.dotx for notes and links about content in the design doc and the module.

Knowledge check unit

In addition to the information in the Module content overview, you should check the knowledge check questions and answers:

  • Do the questions seem to support the learning objectives in the module? The questions should reflect the “takeaways” from the module and should include the most important points in the content.

  • Are the questions complete sentences that end with a question mark? For example, don’t use, “The year that Microsoft was founded:” The correct way to state this question is, “What year was Microsoft founded?”

  • Does the knowledge check have at least two but no more than five questions? If there are more than five questions, ask the SME which question should be removed.

  • Is there information in the module that teaches the information needed to answer the questions?

  • Are any of the questions true/false questions? These aren’t allowed. Let the SME know they need to rewrite or replace the question.

  • Do any of the questions have more than one right answer, include “all (or none) of the above”, or have more or less than three possible answers? Only one right answer is allowed, from three possible choices. Let the SME know they need to rewrite or replace the question.

  • Does the question or answer include second person “you”? If so, change the language to third person. For example, change, “What tool would you use to create a spreadsheet?” to “What tool can be used to create a spreadsheet?”

  • Does the question include “not” or “except”? Ask the SME to rewrite the question.

Learning content unit structure

Units that aren’t introduction, knowledge check, exercise, or summary units are called learning content units. A learning content unit is “…a unit that teaches a learner the knowledge needed to solve a portion of the problem presented in the module.” (From How to structure a learning content unit.)

A learning content unit must:

  • Begin with an introductory paragraph that ties the module scenario into the unit and gives a brief overview of the objective of the unit.

    Learn how to write introductions.

  • Include at least 1-3 chunks of learning content that are separated by level 2 headings.

    Important: If the SME decides to add knowledge check questions at the end of learning content units (rather than a dedicated knowledge check unit), every learning content unit should have 1-2 questions. However, we recommend that for microlearning courses, one knowledge check unit as the penultimate unit is used, rather than including questions in every learning content unit (you can’t have both questions in individual units and a standalone knowledge check unit).

Headings and titles

Make sure that the unit titles, file names for the individual markdown files, and headings within units are written correctly. They should:

  • Be written as present-tense-verb > task > product.

  • Begin with a verb (Create folders) not a gerund (Creating folders).

  • Be sentence-case. The first letter of the first word and product names should be capitalized; all other words should be lower-case.

    Note: The first heading in a learning content unit is a heading 2; you shouldn’t ever use a heading 1.

Review the module for clarity, language, and writing style

Read all of the module text and check it for clarity, language, and writing style, including writing with compliance in mind, and aspects that are specific to microlearning.

Content clarity

As you read the module, think from the perspective of a student with no instructor and ask:

  • Does the content make sense? Would it benefit from an example or analogy?

  • Does it seem to fit the audience? Is it too technical? Or too simple?

  • Does the flow of content generally work?

  • Would the content benefit from integrating the course scenario more often? (The scenario should be included in the introduction paragraph of each learning content unit.)

  • Does the content need to be chunked into subheadings?

  • Would a visual or table help with clarity?

  • Should any of the content be made into an alert (a note)? Tips and tricks, asides, warnings, and other tangential information are encouraged in the microlearning style. You can choose from: note, tip, important, caution, or warning.

    Learn how to add an alert.

Language

General tips for language include:

  • Use the second person “you” in the module and in procedure steps (instructions) in exercises.

    • Exception: In knowledge checks, use only the third person and don’t use the second person (“you”), as per Microsoft Learn’s guidance.

  • Use contractions for an informal tone, such as you’ll, won’t, and can’t.

  • Spell out acronyms on first mention in the module (you don’t need to spell them out for each unit).

  • Run a (Microsoft Word) spell check with grammar checking on.

  • Make sure that the module uses the correct spelling and capitalization of app and tool names. You can ask the SME for guidance, refer to screenshots the SME created for the module, reference Term Studio, or ask the Copy Editor for the course.

Writing style

Check that the module adheres to the Microsoft writing style by correcting passive writing, disjointed ideas, unclear or confusing writing, or writing that isn’t Microsoft style.

Refer to the Microsoft Writing Style Guide external link for more information.

Also ensure that the module content:

  • Focuses on brevity where possible. Avoid long, complex sentences and trim redundant content. Keep it simple! Think of someone skimming the text on the train to work.

  • Adheres to the Microsoft writing style for exercise and procedure steps external link.

  • Uses headings to structure the unit text. Note that the first paragraph in a unit is never a heading, and the highest level of heading is a level 2 heading.

Warning: Sometimes, editing a module doc in Teams or online removes the heading styles from the document. The headings might still look like headings—the styling might not be removed—but they won’t become headings in the markdown files when the MLS converts the Word module document.

  • To check, position the cursor in a heading paragraph and check the Style Gallery on the Home tab in Word’s ribbon. The style that’s highlighted should be a heading style. Another method to check paragraph styles is to turn on the Style area (Options > Advanced > Display > Style area pane width in Draft and Outline Views, enter 1) and then view the document in Draft view (View > Views > Draft).

Word options dialog listing options for viewing Word's style area

  • Uses lists and tables whenever possible or appropriate to explain ideas, rather than paragraphs.

  • Doesn’t use content that is plagiarized. If the module content sounds like it was “lifted” from another source, search for phrases in a search engine. This applies to content on Microsoft Docs and Azure websites.

Tip: When searching online for a phrase, put the text inside quotation marks to return more focused results.

  • Doesn’t sound like marketing. Any content that sounds like it’s “selling” the product:

    • Isn’t our style.

    • Has a high probability that it was lifted from another website.

Compliance

To ensure that the module content is as accessible as possible to as many people as possible, as you are reviewing the module text, be mindful of the following:

  • Ensure alt-text exists for all images. Alt-text should give the meaning of the image, the takeaway – not describe the visual.

    • If the SME has explained a diagram only in the alt-text and not in the surrounding text, suggest to them that the explanation would be useful to everyone if it was included in the text of the unit instead.

    • If most of the explanation for a graphic is in the surrounding text, the alt-text can be much simpler, because it only needs to identify the graphic in a general way.

    • Alt-text should be no longer than 120 characters.

  • If videos are referenced, ensure the video has closed captioning.

  • Compliant language. Change words like view, click, and directional language like below. Refer to the following table for guidance.

Inclusive word choices

To make the content as accessible as possible, be aware of the word choices in the module. Here are some ideas for replacing non-compliance words with more inclusive ones.

Bad Good
Click Select or Enter
Press Select
Type Enter
Right-click Right-click or access the context menu
Double-click Double-click or select [the item] and then select Enter (or whatever the equivalent action is for the task)
Look at, see, show, watch, view, read Notice, observe, refer to, study
Directional language such as: On top of, To the right of, To the left of, At the bottom, Above, Below Do not use visual location only. Refer to what you are drawing attention to by name where possible. For example: In the Name text box, The drop-down box that appears after the Category drop-down list.
Magnifying glass button (screen readers do not describe controls) Do not use visual description only. Refer to what you are drawing attention to by name. For example: The Zoom option (magnifying glass)
Hear Understand, observe, pay attention

Learn more about Accessibility guidelines and requirements, or reference the Accessibility checklist.

Review additional module components

In addition to the specific Microsoft Learn requirements and general writing, review the following components of the module.

Graphics

If a request was made to create a custom graphic, ensure that you are using the most-recent graphic. In addition:

  • Make sure alt-text exists for all images (refer to Compliance items further in this page).

  • Make sure text before the image introduces/explains the ideas communicated in the image.

  • As best you can, make sure all diagrams clearly communicate intended concept

Note: Images in microlearning don’t need figure captions.

Tables

Examine the content of any tables to make sure none of the header cells (the first row in the table) are empty. Table cells in microlearning can’t be empty, so if there are any cells in the rest of the table that are empty, check with the SME to decide what content you can put in the cell that would make sense. For example, if a table is conveying measurements and empty cells mean that there is no measurement, you might put “not measured” or “n/a”.

Note: Tables in microlearning don’t need table captions.

A few points to check for all hyperlinks:

  • Links must be to an approved source, which is typically Microsoft (Docs.microsoft.com) or Azure (Azure.microsoft.com).

  • Microlearning doesn’t use AKA links.

  • Links should have ?azure-portal=true at the end. Note that this is case-sensitive. For example: `https://docs.microsoft.com/learn/paths/explore-microsoft-azure-cloud-concepts/?azure-portal=true

  • If present, remove en-us from the url. If links contain en-us, it causes a build error.

  • Check to be sure that links are only included:

    • In the Summary unit.

    • In other units because they are needed specifically to set up an environment for an exercise.

Definitions of terminology

Check to be sure that definitions are included for all introduced terminology. Also check that all acronyms are defined the first time they’re used in the module.

Fictitious names

Individual and company fictitious names used in examples or exercise must be taken from the Microsoft CELAWeb Approved fictitious names & guidelines. Your Project Manager (PjM) will acquire and provide a list for you to use at the beginning of the project.

Third-party references

In general, avoid references to third-party products, websites, logos, etc., in both text and graphics.

Refer to [Module writing guidance] for more specific information about using third-party reference. Also, you can contact your PjM for specific information about the module you’re working on.

Give feedback to the SME

Because the ID review of the module is done in the module (which is at this point a Word document), turn on Word’s Track Changes feature (Review tab > Tracking > Track Changes) and make changes directly to the text when you’re sure of your change. If changes might alter the technical content or intended meaning, add a comment for the author to verify the change.

In comments, try to make clear, easy to implement suggestions, instead of general commentary. For example, it’s helpful when adding comments to include a suggestion, if you can write one. For example, instead of just “This is confusing,” you can write, “This is confusing. What about: <insert suggested text.>?”

For significant changes, the best practice is to either suggest the change as was previously mentioned, or include the previous content in a comment: The original text was:…

Tip: Consider chatting on Teams with the author to ask questions and resolve content issues. Especially when faced with complex edits, a quick chat can speed up the review process for both of you.