This repo is designed to help you create and scaffold your Student/Step 0 content for Microsoft Learn.
If you've found this repo, but haven't yet:
- Read our Student/Step 0 content strategy doc
- Reached out to Shana Matthews (shanama)
Please take those steps before starting on your content creation journey.
Talk about the general process:
- Do your research:
- Does this content already exist? What are you bringing new?
- Will this work on a student account? (not a deal breaker if not, but would be nice)
- Will this work on Mac and PC? How about browser (with CodeSpaces)?
- Propose to Shana 💍 with these instructions
- Decide on a timeline for project completion
- Decide what you're building (module, lp)
- Outline it using this module design template and share with Shana to ensure it is the right size and format
- Review the Learn content requirements
- Clone this template repo
- Write your content
- Work with Shana to fill in the yml files
- Get someone to review it
- Deliver the repo to Shana
- Respond to PR/DevOps requests from Aquent in the Learn repo
- Review the content once it's live
- Participate in a monthly bug bash (if necessary for your content, Shana will let you know)
So you want to write a module on it's own or part of a learning path, great!
- Module Folder:
- index.yml: Contains the outline of the content and the actual titles, descriptions, etc
- unit.yml (for each unit): Contains the outline of the content and the actual titles, descriptions, etc
- Each module should have an introduction.yml and summary.yml file
- summary.yml: Additionally contains the knowledge check questions (see below)
- Media Folder
- README.md: Table containing the file, URL, Date Accesses, and Copyright information if taken from the web for an easy legal review if necessary
- All images/media to be used throughout the module
- Includes Folder
- unit.md (for each unit): Contains the actual content for each unit
- Each module should have an introduction.md and summary.md file
All modules are required to either have at least one knowledge check or at least one hands-on exercise unit that uses the sandbox in some way. Having both is better.
We recommend having at least one knowledge check per module, even if you do have hands-on exercises that use the sandbox. Knowledge checks are:
- Multiple choice (no True/False)
- Don't have "All/None of the above" as an option
- Should actually contribute to learning
- Need to have the correct answer indicated
- Need to have explanations for why each answer is either correct or incorrect
Knowledge checks can be embedded in a unit or a standalone unit. If embedded, knowledge checks should be 2-3 questions. If standalone, they must be the second-to-last unit in a module and must be 3-5 questions. They should not be combined with the Summary unit, instead they should come right before.
So you decided to build a Learning Path for your Modules! Awesome!
Learning paths are defined by a single index.yml file.
LP Folder
- README.md: Contains the LP title and the Module Titles for quick reference
- index.yml: Contains the outline of the Modules within the Learning Path and the actual titles, descriptions, etc
All of our content will begin localization into the 17 Azure languages (described here on the Learn GitHub repo) the date of the English publication. It takes approximately 2 weeks to localize.
Please check the Learn GitHub docs to ensure these are still up to date.
Locale | Locale Name |
---|---|
de-DE | German - Germany |
es-ES | Spanish - Spain (Traditional Sort) |
fr-FR | French - France |
it-IT | Italian - Italy |
ja-JP | Japanese - Japan |
ko-KR | Korean - Korea |
pt-BR | Portuguese - Brazil |
ru-RU | Russian - Russia |
zh-CN | Chinese - People's Republic of China |
zh-TW | Chinese - Taiwan |
cs-CZ | Czech - Czech Republic |
pl-PL | Polish - Poland |
tr-TR | Turkish - Turkey |
hu-HU | Hungarian - Hungary |
nl-NL | Dutch - Netherlands |
pt-PT | Portuguese - Portugal |
sv-SE | Swedish - Sweden |
If you are going to build a module on it's own, we recommend starting from the module-1 folder and deleteing the learning-path-1 folder from your repo. Copy the module-1 folder for each module you want to create.
If you are going to build modules as part of a learning path, copy the lp1-module-1 folder for each module you want to create and the learning-path-1 folder for each learning path you want to create. Module folders do not live within a Learning Path's folder structure.
Don't Forget:
- Rename folders and files to match YOUR content.
- Change the contents of this README to only have the following:
This repo contains new Microsoft Learn content for....< DESCRIBE YOUR CONTENT >
< TO BE FILLED IN WITH SHANA >
Item | Owner | Status | Deadline |
---|---|---|---|
Propose content | < YOUR NAME > | Not Started | < DATE > |
Get content into Learn and with the vendor | @shanama | Not Started | < DATE > |
Request art assets | @shanama | Not Started | < Date > |
Write Content | < YOUR NAME > | Not Started | < DATE > |
Review Content | < YOUR REVIEWER(S) NAME(S) > | Not Started | < DATE > |
Content to Aquent | < YOUR NAME > | Not Started | < DATE > |
Content Draft on Learn | Aquent | Not Started | < DATE > |
Sign off on Content on Learn | < YOUR NAME > | Not Started | < DATE > |
Publish Content | @shanama | Not Started | < DATE > |
Review Live Content | < YOUR NAME > | Not Started | < DATE > |
< Description of content here >
Type | Title | Description | Duration |
---|---|---|---|
Learning Path | My LP 1 | This LP is so cool | |
Module | My M1 as part of LP1 | This module is awesome | 15-45 min |
Module | My M2 as part of LP1 | This module is awesome | 15-45 min |
Module | My M2 as part of LP1 | This module is awesome | 15-45 min |
Learning Path | My LP 2 | This LP is so cool | |
Module | My M1 as part of LP2 | This module is awesome | 15-45 min |
Module | My M2 as part of LP2 | This module is awesome | 15-45 min |
Module | My M2 as part of LP2 | This module is awesome | 15-45 min |
Link to marketing plan: Sarah will have a template for this
For all future flagship partnership Learning Paths / Modules and select modules created in FY20 or FY21 H1 like CMU Cloud Computing and Oxford Edge AI Engineering, we plan to create a multi-modal learning experience, driving users to Learn, that specifically includes:
- A 2-3 minute video that introduces and gives an overview of the Learning Path / Module available on-demand on Channel 9
- A 15-30 minute video walking through each module available on-demand on Channel9.
- [optional] A 1-hr live stream deep-diving into each module, streamed to Learn TV, Twitch, and YouTube as appropriate
We will also create light connective tissue from Learn to these other modalities. e.g.:
- Starting in Q3, when the learning path intro videos/images feature is released, flagship partnership Learning Paths will show a short introduction video inline on the Learning Path’s index page. See mockup in appendix
- If a video is not (yet) available, we will substitute in a high-quality image provided by the partner, and (if appropriate) a link to sign up for the live stream event.
- Flagship partnership Modules and Learning Paths will include text (formatted as tip) indicating that this content is part of a multi-modal learning experience:
- Index page: “This module is part of a multi-modal learning experience. Start the module to see how you can follow along!” with no link. See mockup in appendix
- Intro unit: “This module is part of a multi-modal learning experience. Follow along with a video walkthrough of the module in a new tab.” Links to a 15-30 minute technical overview video on Channel 9. See mockup in appendix
Learning path index page intro text will follow this format:
- Learning Path title includes partner name (“…inspired by ” or “…in partnership with ”). Note: if author attribution on index pages ships in H2, we will utilize this feature instead.
- Inline introduction video, as described in previous section, supported by the learning path intro videos/images feature
- Connective-tissue text (formatted as tip): “This learning path is part of a multi-modal learning experience. Start the first module to see how you can follow along!”, as described in the previous section
- Intro text which introduces partnership, including partner-supplied copy and linking to partner website if required, and hints at technical topics covered
- Additional paragraph(s) to explain technical topics covered
- Bulleted list of Learning Path objectives (exists, required by Learn)
- Bulled list of Prerequisites (exists, required by Learn)
Module index page intro text will follow the same format with these exceptions:
- Module title does NOT include partner name, unless relevant to module
- Module index pages will not contain a video or image (platform constraint)
- Module index page text will briefly re-introduce the partnership, similar to Learning Path
- Connective-tissue text (formatted as tip): “This module is part of a multi-modal learning experience. Start the module to see how you can follow along!”
< Any comments you want to add here, brainstorming, research, etc >
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.
Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.
Privacy information can be found at https://privacy.microsoft.com/en-us/
Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.