Team PSD Manual
2024-03-20
Chapter 1 Team PSD Manual
Welcome to Team PSD’s manual for resources and guides!
Click within chapters and subsections or use the built-in search feature to search throughout the manual for key terms.
1.1 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)
1.1.3 Subheader
Example: This subchapter has subheaders are 1.1.1, 1.1.2, 1.1.3.
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:
1.4 Glossary
@ Mentions: to notify a person on GitHub by using @ before their username. Users in an organization on GitHub can also be a part of a team that can be mentioned.
App: Allows you to automate and improve the GitHub workflow. Team PSD can use apps to automate simple tasks and enforce standards.
Application Programming Interface (API): We use APIs as a call to send data from our GitHub repository to GitHub Apps and Actions.
Assignee: The member that is assigned to an issue or feature card.
Branches: A branch is a parallel version of a GitHub repository. It is contained within the repository, but does not affect the primary or master branch allowing you to work freely without disrupting the “live” version. When you’ve made the changes you want to make, you can merge your branch back into the master branch to publish your changes.
Bug: An existing feature that has been developed and is not working correctly and should be documented in an issue card on GitHub to be resolved.
Card: A movable square within an associated and contain documentation for Issue tasks, Bugs, Features, or Pull Requests. You may see issue cards on GitHub Kanban Trackers and on the ZenHub Workspace Board.
Code of conduct: A document that defines standards for how to engage in a community on GitHub.
Comment: Add comments within GitHub issue cards to keep discussion going all within context.
Compare branch: The branch you use to create a pull request in GitHub. This branch is compared to the base branch you choose for the pull request, and the changes are identified. When the pull request is merged, the base branch is updated with the changes from the compare branch. Also known as the “head branch” of the pull request.
Concurrent Screencast Video: Screencasted videos allows for asynchronous feedback to be provided. These videos consist of users going through the MVP without audio to concurrently focus on the task of seeing/trying out the MVP and whether or not it addresses their user-centered hypotheses and pain points. Videos should be uploaded on the LZPhD YouTube channel.
Continuous Deployment (CD): Automatic releases to a test or production environment if all the tests from the Continuous Integration (See Continuous Integration) process pass.
Continuous Integration (CI): Practice of integrating changes “continuously”, coupled with automated testing to allow for a function and always up-to-date repository base.
Continuous Learning: The Continuous Learning Culture competency describes a set of values and practices that encourage individuals—and the enterprise as a whole—to continually increase knowledge, competence, performance, and innovation.
Community of Practice (COP): Communities of Practice (CoPs) are organized groups of people who have a common interest in a specific technical or business domain. They collaborate regularly to share information, improve their skills, and actively work on advancing the general knowledge of the domain.
Deliverable: A product of a task or group of tasks.
Design Thinking Process: Design Thinking is a customer-centric development process that creates desirable products that are profitable and sustainable over their lifecycle. The Process consists of Emphasizing, Defining, Ideating, Prototyping, and Testing (see Team PSD 2.0 Monthly Process).
Dependency (Blocking/blockers): Use a blocking/blocker to add a dependency on your GitHub issue card to alert others that a task cannot be done without another task or vice versa.
Documentation: Materials or descriptions that provide information about a topic. The team uses documentation to ensure that our work is transparent, reproducible, and understandable for both team members and external partners.
Epic: Epics are ~1 month’s worth of sprints that go by the week. Each month is a new epic (e.g In August, our Epic is aug_epic).
Estimate: Points following the Fibonacci sequence to describe the level of effort, not hours, required to complete an issue or feature. We can think of these as t-shirt sizes:
Expedite: To move the priority of a bug or feature in GitHub to the top of a queue. Expediting is poison to a production system and should be used only in exigent circumstances.
Feature: A characteristic, attribute or topic that requires work breakdown, research, design, development and testing. Features can be tagged as “fast_track” in order to expedite its design and development. The features documentation of requirements will be in a GitHub Feature card and placed in the appropriate feature_tracker column.
Fork: A fork is a personal copy of another user’s GitHub repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original upstream repository. You can also open a pull request in the upstream repository and keep your fork synced with the latest changes since both repositories are still connected.
Git: Git is an open source program for tracking changes in text files. It was written by the author of the Linux operating system, and is the core technology that GitHub, the social and user interface, is built on top of.
GitHub: Team PSD’s main platform to track work from each Team PSD Workflow (Research, Operations, and Modeling to Learn) based on GitHub repositories.
GitHub Actions: GitHub Actions help automate repository workflows and tasks on GitHub. You can write individual tasks, called actions, and combine them to create a custom workflow. Workflows are custom automated processes that you can set up in your repository to build, test, package, release, or deploy any project on GitHub.
Issue: Issues are an important tasks or problems to be worked on and may be discussed with others to resolve and close in a GitHub Issue card.
Labels: A tag in GitHub that is affixed by an originator or workgroup as a means to identify the task holders for a specific issue. Workgroup leads can filter by labels in the tracker to sort for their specific workgroup or other workgroups’ Kanban cards in the search bar found in the upper right-hand corner of each tracker (below). To use the filter function, use the code “label:labelname” i.e. “label:facilitate” or “label:sim_ui”. (You can use this function with other sort options as well i.e. author:lzim, etc.). In most cases, an issue should only have 1 label at any given time.
LucidCharts: Platform that enables the creation of charts and flows. The team uses LucidCharts for pictorial documentation.
Markdown (language and file format): Markdown is an incredibly simple semantic file format, not too dissimilar from .doc, .rtf and .txt. Markdown makes it easy for even those without a web-publishing background to write prose (including with links, lists, bullets, etc.) and have it displayed like a website. GitHub supports Markdown and uses a particular form of Markdown called GitHub Flavored Markdown.
Master Card: GitHub Master Cards typically do not have an Assignee, Milestone, Estimate, (with the exception of some Manuscript cards for the PI) as their purpose is to document and track all related issue task cards and/or requirements. These cards usually live in their respective Kanban Tracker and/or ZenHub pipeline.
Master Document Card: The Master Document Card is a tracking card on GitHub that tracks all of an Issue task’s requirements and multiple Issue task cards related to 1 big Issue that had to be broken down into small tasks. Master Document Cards flows through the document_tracker Kanban and open_documents ZenHub pipeline.
Master Feature Card: The Master Feature Card is a tracking card on GitHub that tracks a customer requirement through design to testing. It defines a customer’s requirement, design features that support the requirement and test criteria that demonstrate the design criteria meets the customer requirement. Master Feature Cards flows through the feature_tracker Kanban and open_features ZenHub pipeline.
Master Manuscript Card: The Master Manuscript Card is a tracking card on GitHub that tracks all of an Manuscript related Issue task’s requirements and multiple Issue task cards related to 1 big Manuscript Issue that had to be broken down into small tasks. Master Manuscript Cards flows through the manuscript_tracker Kanban and open_manuscripts ZenHub pipeline.
Merge: Merging takes the changes from one branch (in the same GitHub repository or from a fork), and applies them into another on GitHub. This often happens as a “pull request” (which can be thought of as a request to merge), or via the command line. A merge can be done through a pull request via the GitHub.com web interface if there are no conflicting changes, or can always be done via the command line.
Merge conflict: A difference that occurs between merged branches on GitHub. Merge conflicts happen when people make different changes to the same line of the same file, or when one person edits a file and another person deletes the same file. The merge conflict must be resolved before you can merge the branches.
Milestone: Milestones are the monthly workgroup sprints, in which each workgroup tries to accomplish their monthly milestone goals for the monthly epic.
Minimum Viable Product (MVP): A new/revised product that attempts to address a user or user groups pain points and needs (See User-Centered Hypotheses). The MVP should follow the 80/20 Pareto Principle (created with the least amount/20% of effort but solves majority/80% of pain points/needs).
Persona: A description that is used to represent a user or a user groups’ needs and pain points (see User-Centered Hypotheses) with specific skills, goals, attittudes, and the background of the user to account for while creating and prototyping an MVP.
Principles: Rules or beliefs that may be in service of multiple key Values.
Project (Kanban Tracker Board): A board that contains issue cards and is used to communicate the status and priority of bugs, features, documentation, & manuscripts as they move through the production process. There are four Kanban to manage production in the Team PSD are: bug_tracker, feature_tracker, document_tracker, and manuscript_tracker.
Prototyping: Occurs during Week 2 of the Team PSD 2.0 Monthly Process, prototyping is to build or create a final product or MVP (see Minimum Viable Product) as a way to understand what it should do, how it should be interacted, and see how the product or MVP will look like before completion. The user or user groups’ pain points should be taken into account of while prototyping (see User-Centered Hypotheses).
Pull request: Pull requests are proposed changes to a GitHub repository submitted by a user and accepted or rejected by a repository’s collaborators. Like issues, pull requests each have their own discussion forum.
Pull request review: Comments from collaborators on a GitHub pull request that approve the changes or request further changes before the pull request is merged.
Readme: A GitHub text file containing information about the files in a repository that is typically the first file a visitor to your repository will see. A README file, along with a repository license, contribution guidelines, and a code of conduct, helps you share expectations and manage contributions to your project.
Refactoring: Refactoring is needed when we have to make upgrades over time and/or prepare for new, incoming features. Refactoring requires internal changes, without effecting external behavior.
Release: GitHub issues that are grouped into a key team release.
Repository: A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.
Repository (Private): Private GitHub repositories are only visible to the repository owner and collaborators that the owner specified.
Retrospective Verbal: A retrospective verbal is a written out set of feedback and response after the user finishes testing and looking through an MVP and thinking about whether or not the MVP addressed their user-centered hypotheses and pain points.
Second Story Perspectives: A retrospective look during Week 4 of the Team PSD 2.0 Monthly Spring to discuss what happened in the Epic, the results of the Iteration, review their practices, and identify ways to improve for the next Epic.
Task: A cognitive or kinetic behavior that consumes time. A task or group of tasks are necessary to create an outcome or deliverable.
Team PSD 2.0 Monthly Process: The 2.0 Monthly Process for Epics/Milestones follows the design thinking process based on concepts from user experience to scale and make Team PSD’s workflow become asynchronous to better support the needs and pain points (See User-Centered Hypotheses) of a user with a product that can also be integrated by the end of the month for the team to use. The Monthly Process goes by weeks.
- Week 1: Gather user-centered hypotheses
- Week 2: Clarify user assumptions w/ Minimum Viable Product (MVP) test
- Week 3: Review results of user persona testing of your MVP Prototype (with concurrent video and retrospective verbal)
- Week 4: Review user persona artifacts and second story perspectives mindfully and empathically to discover new understandings you might have missed or still need to learn
Team PSD Workflows: Team PSD has 3 workflows: Research, Operations, and Modeling to Learn.
Think Aloud Protocols: These user testing protocols typically involve participants thinking aloud as they are performing a set of specified tasks. Participants are asked to say whatever comes into their mind as they complete the task. This might include what they are looking at, thinking, doing, and feeling. Team PSD does a combination of a concurrent and retrospective think aloud protocol (see Concurrent Screencast Video and Retrospective Verbal).
User Experience: A person’s emotions and attitudes about using a particular product, system/workflow or service. The Team PSD 2.0 Process is based on the foundation of the user’s experience to ensure Products integrated by the end of the monthly Epic address the person’s emotions, attitudes, pain points, and needs.
User Testing: Occurs during Week 3 of the Team PSD 2.0 Process, user testing is the process through which the MVP is tested by the targeted users who perform specific and realistic tasks using the MVP.
User-Centered Hypotheses: Gathered in Week 1 of the Team PSD 2.0 Process, these are the pain point and needs of a user that is struggling in either a task or parts of the workflow within Team PSD’s Operations, Research, and/or Modeling to Learn pipeline. The pain points and needs should be turned into hypotheses that can be tested and reiterated throughout the Team PSD 2.0 Monthly Process cycle to address and resolve the pain points and needs of a user/user group.
Values: Virtues that govern the team’s principles. Values can be in conflict with Principles, especially when it comes to applying Values in any given action.
YAML Ain’t Markup Language (YAML or YML): Data serialization language that is used to set configurations for other applications to read and have information about the document/script. YAML will be used by the team to setup App configurations and in our documentation to enable transfers between other documents. GitHub Action workflow files use .YML files.
ZenHub: A Google Chrome extension that allows agile project management within GitHub.
ZenHub 9 clicks: Every issue card must be in a pipeline, have an assignee, labeled, added dependencies, added to a tracker (if applicable), milestone, epic, estimated with points, in an epic and/or project (if applicable), within a release (if applicable), and associated with pull requests (if necessary).
ZenHub Pipelines: Pipelines are columns within the overall ZenHub Board to show where Issues belong in which pipeline, allowing for a clear and consistent flow of Issues across the Board. You can click on the light grey (i) icon within each pipeline to see the description.
1.5 Acronym
AAHRPP: Association for the Accreditation of Human Research Protection Program
ACCME: Accreditation Council for Continuing Medical Education
ACORP: Animal Component of Research Protocol
ADPAC: Automated Data Processing Application Coordinator
ANCC: American Nurses Credentialing Center
APA: American Psychological Association
ASWB: Association of Social Work Boards
ATS: Addiction Treatment Services
AUD: Alcohol Use Disorder
BHIP: Behavioral Health Integration Project
BISL: Business Intelligence Service Line
CBOC: Community Based Outpatient Clinic
CC: Care Coordination
CFIR: Consolidated Framework for Implementation Research
CHCE: Center for Health Care Evaluation
CPRS: Computerized Patient Record System
CPT Code: Current Procedural Terminology
CRADA: Cooperative Research and Development Agreement
CSP: Cooperative Studies Program
CTR3: Center for Tissue Regeneration, Rehabilitation, and Repair
CWT: Comprehensive Work Therapy
DEA: Drug Enforcement Agency
DHHS: Department of Health & Human Services
EBP: Evidence-Based Practices
EBPharm: Evidence-Based Pharmacotherapy
EBPsy: Evidence-Based Psychotherapy
EES: Employee Education Services
F&A Rate: Facilities & Administrative Rate
FAR: Federal Acquisition Regulations
FTE: Full Time Equivalent
GHPC: Georgia Health Policy Center
GRECC: Geriatric Research, Education and Clinical Center
HERC: Health Economics Resource Center
HSR&D: Health Services Research and Development Services
IACUC: Institutional Animal Care and Use Committee
INAPS: International Association of Peer Supporters
IOP: Intensive Outpatient Program
IPA: Intergovernmental Personnel Act
IRB: Institutional Review Board
JPA: Joint Personnel Agreement
LD: Livermore Division
MAT: Medication Assisted Therapy
MHICM: Mental Health Intensive Case Management
MHTC: Mental Health Treatment Coordinators
MIRECC: Mental Illness Research, Education, and Clinical Center
MM: Medication Management
MPD: Menlo Park Division
NAVREF: National Association of Veteran’s Research and Education Foundations
NBCC: National Board for Certified Counselors
NCPTSD-DT: National Center for Posttraumatic Stress Disorder, Dissemination & Training
NIH: National Institutes of Health
OGC: Office of General Counsel
OMB: Office of Management & Budget
OMHO: Office of Mental Health Operations (now OMHSP)
OMHSP: Office of Mental Health & Suicide Prevention (previously OMHO)
OPM: Office of Personnel Management
ORO: Office of Research Oversight
OUD: Opioid Use Disorder
PAD: Palo Alto Division
PAIRE: Palo Alto Institute for Research and Education, Inc.
PAVIR: Palo Alto Veterans Institute for Research
PCP: Primary Care PHysician
PCT: PTSD Clinical Team
PE: Prolonged Exposure
PERC: Program Evaluation and Resource Center
PHI: Protected Health Information
PI: Prinicipal Investigator
PSA: Personal Services Agreement
PSD: Participatory System Dynamics
QI: Quality Improvement
QIIC: Quality Improvement Implementation Consultant
R&DC: Research and Development Committee
RDIS: Research and Development Information System
rJPA: Reverse Joint Personnel Agreement
SAIL: Strategic Analytics for Improvement and Learning
Sankey: A type of flow diagram where the width of the arrows are proportional to the flow quantity
“Say File”: GitHub file for the facilitators to read from
“See File”: GitHub file for learners to look at at
SME: Subject Matter Expert
SMI: Serious Mental Illness
SRC: Scientific Review Committee
SRS: Subcommittee on Research Safety
SU: Stanford University
SUD: Substance Use Disorder
UI: User Interface
VA: Veterans Affairs
VAPAHCS: Veterans Affairs Palo Alto Health Care System
VAPOR: Veterans Advisory Partnership for Operations and Research
VERC: Veterans Engineering Resource Center
VHA: Veterans Health Administration
VISN: Veterans Integrated Service Network
VISTA: Veterans Health Information Systems and Technology Architecture
WCC: Women’s Counseling Center
WRIISC: War Related Illness & Injury Study Center
WRVU: Work Relative Value Unit
X Waiver: Needed to prescribe buprenorphine; must complete training and still limits # of patients per physician that can receive bup
test commit
1.7 Metadata
#how_to_video #user_story #data_feeds
#mtl_learner #mtl_facilitator #teampsd_howto #mtl_admin #data_oit #data_omhsp #data_teampsd
1.9 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
- Example: feature-gh-pages_chapter_11
1.10 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
1.11 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
1.12 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.
1.13 Check your file against the GH Actions by making a pull request to the GH-Pages master branch.
- 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, Link, and Linter checkers.
- Click on “Details” in the ActionChecker Action to be navigated to the Spell, Link, and Linter checkers.
- Once edits based on failed checks and feedback from reviewers have been implemented, merge the Feature branch into the GH-Pages branch.
1.14 Publish your Chapter to master GH-pages branch.
Merge the Feature branch into GH-pages’s master branch and double check that your chapter was published at https://mtl.how/teampsd_manual