Chapter 2 Use and Contribute to this Manual
2.1 Click the Table of Contents
The Team PSD Manual’s table of contents is clickable and separates into 3 header styles:
- Main Chapter
- Subchapter
- Subheader (nested within Subchapter)
2.1.3 Subheader
Example: This chapter’s subheaders are 2.1.1, 2.1.2, 2.1.3 which focuses on the 3 different header styles.
Note: Subheaders are nested within subchapters and not directly seen unless the subchapter is first clicked on.
Unclicked subchapter (this is by default):
Clicked subchapter that reveals subheaders:
2.2 Ctrl+F Key Terms
To search for key terms throughout the entire manual, use the built-in Ctrl+F function in the manual.
Use your laptop’s keyboard to Ctrl+F or Cmd+F to search within chapters if you already know which chapter a key term you are looking for is in, but unsure where within that chapter,
To use the built-in Ctrl-F function:
Click on the magnifying glass icon in the header at the top of the manual.
Type in the search box the key term(s) you are searching throughout the entire manual.
The chapters where the key term was found in will appear in the Table of Contents.
- To look through all of the instances, click the Enter button on your keyboard:
- To look within a chapter from the Table of Contents, click on the chapter you want to search in and click Enter to look through the instances in that chapter:
- Clicked on the Glossary chapter for example
2.3 Contribute to the Manual Using GitHub
2.3.1 Create a Feature Branch from the GH-Pages Branch
- Start by creating a feature branch with the beginning of the branch named “feature-gh-pages”.
- Name your branch according to the content you’re revising or adding—for context and so it’s easily identifiable.
- Example: feature-gh-pages_chapter_11
- Note: It is important your branch name starts with the exact syntax as shown above! This naming structure evokes the relevant linter actions.
You can now work within the newly created branch. Select an existing markdown file to edit or create a new markdown (.md) file following the instructions below.
2.3.2 Create a New Markdown File
Notes: - Use the naming convention: (chapter #)(title of your chapter).md - Example: 11.0_ms_teams.md - Use all lowercase and underscores () instead of spaces. - File name must end in “.md” to indicate a markdown file (so markdown syntax will work correctly). - If your chapter is long, break your markdown file into sectioned markdown files to easily find the section of the chapter you want to edit. - Example: 4.3_improve_team_psd_manual.md
2.3.3 Edit/Format the Markdown (.md) File
2.3.3.1 Heading Rules
- Header 1: Title of Chapter — syntax=
# (name of chapter) - Header 2: Main Sections of the Chapter — syntax=
## (name of section) - Header 3 (hidden unless Header 2 is clicked on in the manual): Sub-level for the main section — syntax=
### (name of sub-level heading) - Header 4 (hidden within the content of Header 3): Use to further indicate additional sections/sub-headings within a chapter — syntax=
#### (name of further sub-level heading)
Examples:
The following shows examples of headings within the manual—first, the markup syntax for headers, then a screenshot of what these headers look like in the table of contents and the manual.
- Header 1:
# Standard Operations - Header 2:
## Project Trackers - Header 3:
### bug_tracker - Header 4:
#### Types of Bugs
| Table of Contents Headings | Manual Headings |
|---|---|
 |
 |
2.3.4 Add Markdown File Name in the “_bookdown.yml” File
The “bookdown.yml” file prints out the manual in the order of the the markdown files listed in line 6 (and beyond), always beginning with
index.Rmd, followed by .md file names.Add your markdown file name where you want the file to appear in the manual.
- Note: Make sure to include quotations around the file name and a comma, if needed!
This is a great way to check the formatting and output of your markdown file in the actual Manual before you submit a pull request.
2.3.5 Create a Pull Request
There are several ways to create a pull request; below is one example.
- Navigate to the Pull requests tab on the top navbar in GitHub.
- Click the New pull request button.
- Click the
base:dropdown, then select gh-pages.
- Click the
compare:dropdown, and select your feature branch.
- Check that you are pulling the feature branch into the gh-pages head branch. You should see an “Able to merge.” message.
- Click the Create pull request button. A pull request form will appear.
- Fill out the necessary information. Then click the Create pull request button.
2.3.6 Check the File Against GitHub Actions
Once a pull request has been made, an automatic process checks the file(s) against the repo’s Linter Actions. Scroll down the pull request page to see real-time progress of the Linter Actions. The screenshot below shows Actions in progress with no issues so far in the checks:
2.3.6.1 Linter Actions
Linter Actions are automated processes that check your code for issues, errors, or style violations based on predefined rules. The linters for this repo fire automatically when a pull request is made. The purpose of these actions are to ensure code quality, maintain consistency, and catch errors early.
Note: Linter Actions will not fire if the feature branch name is does not follow the exact syntax needed (see Create a Feature Branch from the GH-Pages Branch).
Review Linter Results
If the Actions progress area has a red X and “All checks have failed” message (like the screenshot below), click on Details in the ActionChecker to navigate to the Spell Checker, Markdown Link Checker, and Markdown Linter for Directory Level Scan. The ActionChecker returns the “All checks have failed” error with any failed action (one or many). A failing ActionChecker does not prevent one from deploying updates to the manual; although “All checks have failed”, users can still merge their pull request (see Publish to the Master gh-pages Branch).
ActionChecker details screen:
Check for a red “X” by each GitHub Action and read the output of where errors occurred. Some errors you can address yourself, some are safely ignorable, and others may need to be addressed by the Development Team. As a reminder, errors do not prevent changes from happening; you can still merge the pull request.
2.3.6.2 Editors
There are several editor actions that will screen your documents for proper format, valid links, and compliance with editorial rules and spelling. Editors refer to tools or interfaces where you can directly edit (correct) code or files if the editor actions returned errors.
- The Spell Checker checks for spelling errors or unknown acronyms in your commit and its associated files. This check usually passes with no errors. If the spell checker throws an error, you may need to either 1) correct a spelling mistake in your document or 2) add it to Team PSD’s custom dictionary file the Spell Checker uses.
Click the caret next to Spell Checker to reveal the spelling errors found. In the image below, lines 14-18 identify unknown words and/or spelling mistakes.
2.3.6.2.1 Correct a Misspelling in a Markdown File
From the example above, there is one misspelling: chapterr. The Spell Checker shows the line number in which spelling errors were found.
We can tell that this spelling mistake is in line #190 of the document “2.0_use_and_contribute_to_teampsd_manual.md”.
Go to the identified markdown file, correct the mistake, and make a commit.
2.3.6.2.2 Update cspellcdict.txt
From the example above, there are two unknown words: “callouts” and “GH”. The custom dictionary file can be amended so these errors won’t show again (for those specific words).
To do this, navigate to the repo you’re working within (in this example, it’s the teampsd repo), select the gh-pages branch (not the feature branch you’ve been working in), and click the .github/workflows folder. Then click on cspellcdict.txt (Team PSD’s custom dictionary).
Edit this file by adding the previously unknown word(s)/acronyms to the list. Bonus points if you add them in the correct alphabetical order! As seen in the screenshot below, both unknown words were added. Your future self (and teammates) may appreciate singular and/or plural versions of a word being added to this file, too. Commit your changes when done.
- The Markdown Link Checker tests all the links in your document to make sure they work correctly. Links include hyperlinks to internal and external (to VA domain) webpages, links to image files, and links to content within the document itself.
Click the caret next to Markdown Link Checker to reveal the status of all links within your committed files. Scroll past the colored text until you see a checkmark (working link) or an X (non-working link) within brackets beside each link.
Examples of the different types of links are shown below:
*It is normal for this checker to throw errors for links within the VA domain. These can safely be ignored.
Make any link corrections needed within the document(s) and commit your changes.
- The Markdown Linter for Directory Level Scan tests your markdown file for compliance with markdown editorial rules. For example, it checks for additional spaces after each line, proper sequence of headers, bulleted lists, and other basic editorial screenings. If any formatting errors like the ones below are identified, they can be safely ignored and the pull request can be merged. The image below shows how to “read” the error messages for this linter.
If you desire a deep dive into the rules this linter checks for, this is a good resource.
2.3.7 Publish to the Master gh-pages Branch
Once you have reviewed ActionChecker details and addressed any critical errors, you can request teammates review your pull request. Depending on their feedback, you may need to respond to their comments or questions.
You can merge the pull request yourself. Remember, errors do not prevent changes from happening; you can still merge. It is always possible to revert changes (pull requests). To merge the pull request, return to the Pull requests tab, navigate to your pull request, and click the Merge pull request button:
Then click the Confirm merge button:
Follow the progress of your merge by clicking the Actions tab. Be patient; it can take a few minutes for the workflows to complete. An example of the status change is provided below:
Once you see a green status next to “pages build and deployment”, double-check that your chapter was published at https://mtl.how/teampsd_manual.
2.3.8 Delete the Feature Branch
Once you observe your changes live in the manual, please delete the feature branch to help reduce clutter. This can be done in two ways:
- Click the Delete branch button on the pull request:
—OR—
- Navigate to the teampsd repo, click the master branch dropdown, and select View all branches. Locate your feature branch and click the trash can icon on the right-hand side of the screen:
