Chapter 2 Use and Contribute to this Manual
2.2 Click 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.2.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.3 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.4 Contribute to Manual using GitHub
2.4.1 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”.
- Example: feature-gh-pages_chapter_11
2.4.2 2. Create a new markdown file into the branch.
- Naming convention: chapter_(chapter # here)_(title of your chapter).md
- Example: chapter_4_teampsd_monthly_process.md
- Note: If your chapter is very long, break down your markdown file into sectioned markdown files to easily find the section of the chapter you want to edit.
- Example: chapter_4.3_teampsd_monthly_process_week_3.md
2.4.3 3. Edit/format your markdown file.
Heading Rules
- Header 1: Title of Chapter
- Header 2: Main Sections of the Chapter
- Header 3 (hidden unless Header 2 is clicked on in the manual): Sub-level for the main section.
- Header 4 (hidden within the content of Header 3): Use to further indicate additional sections/sub-headings within a chapter.
Example: - Header 1: Team PSD 2.0 Monthly Process - Header 2: Week 3: Review User Results of MVP - Header 3: 4.3.1 Create Screencast Video - Header 4: 4.3.1.1 Instructions
2.4.4 4. Add markdown file name in the “_bookdown.yml” file.
The “bookdown.yml” prints out the manual in the order of the the markdown files listed in line 6
rmd_files:.Add your markdown file name in the order of which the file should appear in the manual in line 6 within the brackets.
- 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 hand off the review for QA Test.
2.4.5 5. Check your file against the GH Actions by making a pull request to the GH-Pages master branch.
2.4.5.1 Editors
There are several editor actions that will screen your documents for proper format, compliance with editorial rules and spelling.
- The Markdown Editor 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. Below are steps to follow to use this test.
- The Link Checker will test all the links in your document to make sure they work. Recommend running this action from inside the VA Domain, as some domain links will return an error if you test outside the domain.
- The APA Editor tests your markdown file for compliance with APA rules for the use of prepositions in titles, special characters, bulleted questions and abbreviations.
- Procedure:
- Assign QA Test reviewers and check for a red X by each GH Action and read the output of where errors occurred.
- Click on “Details” in the ActionChecker Action to be navigated to the Spell Checker, Link Checker, Markdown Editor and APA Editors.
- Once edits based on failed checks and feedback from reviewers have been implemented, merge the Feature branch into the GH-Pages branch.
2.4.6 6. Publish your Chapter to master GH-pages branch.
Merge the Feature branch into GH-page’s master branch and double check that your chapter was published at https://mtl.how/teampsd_manual