Chapter 2 Introduction - Modeling to Learn Manual

Welcome to the Modeling to Learn for learners, facilitators, and administrators.

Click within chapters and subsections or use the built-in search feature using the magnifying glass in the top left to search throughout the manual for keywords.

2.1 MTL Blue vs. Red Map

2.2 MTL is a partnership.

• We are listening every single day to all of our partners, and we are always learning.
• You may see a bug or issue that should be addressed.
• Please use GitHub bring it to the attention of Team PSD.

2.3 Report an issue or bug to Team PSD

1. Go to mtl.how/bugs.
2. Click on the Issues tab.

3. Click the green “New Issue” button.
4. Create an “Issue” by clicking the green “Get Started” button.

5. Edit the template information to the details of your issue and click the green “Submit new issue” button.

2.4 Improve the Modeling to Learn Repo by Using GitHub

• Value Stream: Operations
• Workstream: PeopleOps
• Workflow: facilitate_workflow
• Video: Essential Team PSD GitHub Skills - To navigate to specific points within this video, click the Chapters button on the right-hand side of the playback screen. Different subject start times are bookmarked so you can go directly to the content of interest. Recorded 11/2023.
• Video: Back out a merged branch (revert) - Recorded 11/2023.
• Video - Watch to learn how to improve the Modeling to Learn 3.0 manual resources at mtl.how. Dr. Zimmerman and Mushiana review and post the updated MTL 3.0 Facilitator Fidelity guides for the PARTNER phase to the MTL Blue s01-s04 facilitator folders. Recorded 5/2022.

Teams Channel Link - from training_workflow, 11/2/23.

Teams Channel Link - from training_workflow, 5/26/22.

Teams Channel Link - from mtl_facilitate > general, 5/20/22.

2.4.1 Contribute to the MTL Repo

Note: You must have an activated GitHub account before making contributions. If you do not have a GitHub account, follow these instructions:

1. Use this YourIT link for comprehensive GitHub account access instructions.
2. When you receive a GitHub organization or repo invitation, accept it.
3. Lindsey must invite you to be a collaborator and you must accept the invitation (via the same email account you’ve linked to GitHub) before any contributions can be made.

Once you have an activated GitHub account, you can contribute to the MTL Repo and Manual.

1. Navigate to mtl.how.
2. Click the master branch drop-down menu.
3. In the “Find or create a branch…” field, type in the name of this new branch using this naming convention: feature-(meaningful_name).
   • Example: feature-s02_partner_fidelity
   • Note: Typing “feature-“ at the beginning of the branch name will cause linter actions to fire when committing the file (including checks for Markdown editorial rules, broken links, APA style adherence, and spelling).
   • Congratulations! You’ve just made your own feature branch, where you can make your modifications, additions, and deletions.
4. Navigate to and click on the file you want to modify within the feature branch you just created.
5. Select the pencil icon (hover text: Edit this file) button.
6. Modify the file content.
   • Edit file tab (pencil icon): this is where you need to be to actively edit the code, play with formatting, etc.
   • Preview tab: displays what code will look like when published.
   • Manual files are written in Markdown, a light (i.e., simple) formatting language. Below are some examples of the syntax used for basic formatting in the manual. For more markdown formatting information, go to: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax or Google it.

Element	Markdown Syntax
Headings	#, ##, ###, ####, #####, ######
Bold	** before and after text you want boldfaced
Italic	_ before and after text you want italicized
Bold + Italic	**_ before and after text you want boldfaced and italicized
Blockquote	>
Ordered List	begin line with “1.”, then a space, then your numbered item text, continue list by pressing Enter
Unordered List	begin line with “-”, then a space, then your bullet item text, continue list by pressing Enter
Code	` before and after text you want to appear as code
Horizontal Rule	—

7. Commit your file when you are done working on it by clicking the green Commit changes… button.
   • In the Commit message field, give a brief description of your modifications (e.g., “Copied the X file into Y.” or “Added information about…”.).
   • Use the Extended description field if needed to provide further or detailed information about your modifications.
   • Notes:
     • When you commit a file, you are recording changes to one or more files in your branch. Each commit is assigned a unique ID that identifies the specific changes that were made, when they were made, and who created the changes.
     • Don’t be afraid! You’ve just committed the new file to your newly created branch. Also, nobody can “break” things in GitHub; changes can always be reverted.
     • Do not leave your uncommitted modified markdown file overnight. Until you have committed it, there is no cloud saving and no backup. If your VPN/VA connection is lost and you have not saved, you will lose all your work in this file.

2.4.2 Contribute to the MTL Manual

This manual is created using GitHub Pages (gh-pages). GitHub Pages is a web hosting service that allows users to create and host websites directly from their GitHub repositories.

1. Navigate to mtl.how.

2. Click the master branch drop-down menu.

3. Select gh-pages.

   • Note: the gh-pages branch serves as the “master” for the manuals.

4. Create a feature branch from the gh-pages branch.

   1. Click the gh-pages drop-down menu.

   2. In the “Find or create a branch…” field, type in the name of this new branch using this naming convention: feature-gh-pages_(chapter #)_(title of chapter).

   • Example: feature-gh-pages_chapter_7.0_mtl_technical_manual_facilitator
   • Note: Typing “feature-“ at the beginning of the branch name will cause linter actions to fire when committing the file (including checks for Markdown editorial rules, broken links, APA style adherence, and spelling).
   • Congratulations! You’ve just made your own feature branch, where you can make your modifications, additions, and deletions.

2.4.2.1 Edit an Existing Markdown (.md) File

1. Navigate to and open the .md file you want to modify within the feature branch.
2. Select the pencil icon button (hover text: Edit this file).
3. Modify the file content.
4. Click the Commit changes… button when you are done making modifications to the file.

2.4.2.2 Create a New Markdown File

1. Click the Add file drop-down menu.
2. Select Create new file.
3. In the Name your file… field, type in the name of your new file using this naming convention: (chapter #)_(chapter title).md.
   • The “.md” at the end of your file name is important; this file extension is how GitHub recognizes it as a Markdown file and understands formatting codes you use within your file.
   • When creating a new chapter or subsection within the manual, be sure to number the file name accordingly.
   • Use only lowercase.
   • Use underscores in lieu of spaces.
   • File names are usually the title of the chapter/subsection.
4. In the Edit/Preview pane, develop your content.
5. Click the Commit changes… button when you are done making modifications to the file.

2.4.3 Create a Pull Request

Once you are finished committing changes to an existing file or have created a new Markdown file in the repo, it is time to create a pull request. Pull requests serve as a structured approach to managing code changes, enabling code review, discussion, testing, and documentation updates before changes are merged into the main codebase.

1. Navigate to the Pull requests tab within GitHub.
2. Click the green New pull request button.
3. In the compare: drop-down menu, select the branch you modified.
4. In the base: drop-down menu, select master.
   • Note: You are “pulling” the changes from the right to the left. The arrow between the two fields is a good visual reminder of this.
   • This means you are requesting information to be pulled into the master branch from the feature branch you created.
   • As you scroll down, you can see red and green highlighted information; red = deletions, green = additions.
5. Click the green Create pull request button.
6. A review page will appear where you can:
   • Add a short summary of the changes between your feature branch and the repository’s base branch.
   • Review the changes made by commits.
   • Add Pipelines, Reviewer/s, Assignee/s (usually you, the one making changes), Label/s, Project/s, Milestone/s, and Estimate (story points).