Team PSD Manual

[lzim]

Begin to organize and compile our Team PSD Manual on GitHub using bookdown. See https://bookdown.org/yihui/bookdown/github.html

@anthonycpichardo and @staceypark I’m just catching up over the weekend, but this issue card is something not for the weekend, obs...🤸🏻‍♀️

But, please do alert workgroup leads to the need to compile their resources by referencing this issue during Monday’s 8AM workgroup leads meeting. I have added it to New Business.

• We need to keep our resources in their existing locations, which is where they will continue to live in their work in progress (WIP) state. This task is to synthesize all our resources into an always current Team PSD Manual 📒

Soon we will compile the MTL Manual to be hosted on our mtl repo. We also need to compile a Team PSD Manual to be hosted on our teampsd repo.

Due date is initially set for 3/31 with the hopes that a printed version can ship with #1021. But, as we proceed through the requirements below, we’ll assess when to print/ship, including the possibility of shipping in phases.

This work for this issue card is largely represented by smaller chunks of story points, and many relevant issue card tasks already exist and were closed, or are estimated. So, as document_tracker cards close, the great resources that have been developed or updated, can be added to the manual now or at the same time as they are created (aka the “OHIO method” only hand it once).

But, some of the resources are outside the document_team column and may have more story points worth of work and should be split out and delegated.

• Others will complete documentation, but you two will lead compilation on GitHub, not individual team members.

I see this as a 5 inter-related manual-building requirements:

• Requirement 1) Bookdown on GitHub - Review the link above for technological options about hosting a bookdown manual on each of our GitHub Repos. I welcome advise from you two about how best to approach the compilation and publishing of our Team PSD Manual and our MTL Manual on the two GitHub repos. _Please add this to our agenda for me to hear your recommendations at our Thursday 3/19 hq_workgroup meeting_
• Requirement 2) Table of Contents - Finalize inventory all the existing documentation that should be included and create decision rules for a) when documentation is needed, and b) what type of documentation is needed (e.g., manual, guide, checklist, SOP, map, cheat sheet, video, trainings, etc).
• Requirement 3) Compile Documentation - add to GitHub as we close document_tracker cards.
• Requirement 4) Produce any missing Documentation - add to GitHub as we close document_tracker cards.
• Requirement 5) Print and ship Team PSD manual w/MTL Manual - coordinate with #1021 OR send in second shipment. NOTE: QIICs will need this well in advance of session 1 or part 1 in order to adequately prepare.

Team PSD Manual Organization (first draft TOC):

3 sections

1. Project Management
2. Operations (our team will continue to use “Processes” and “Platforms” instead of operations
3. Product Management (our team uses “Resources” instead of product).

A. Orientation to Team PSD Project Management

• Team PSD Workgroups & Responsibilities (org chart)
• Use of Team PSD meetings and huddles
• A large part of the Team PSD SOP

B. Orientation to Team PSD Processes & Platforms

• SOPs that reflect Daily Workflow processes in including ZenHub Epics, etc.
• Team PSD Platforms & when to use them for key tasks

C. Orientation to Team PSD Resources

• SOPs that reflect testing FAST & SLOW
• Trainings and documentation for Redcap, Data UI, Splashpage, MTL Sim UI, etc.

Order of the Manual Resources with sections A, B, & C

1. SOP (Team PSD Workgroups & Meetings Workflow, TEST and FAST testing policy, COP guidelines and management)
2. map (mtl.how, document, ZenHub)
3. guides (SEE & SAY...others? OSF projects, RedCap, ReqlLogic?)
4. trainings (review training_tracker)
5. testing protocols (Sim, Data, etc.)
6. checklists (AM & hq huddle “pop-quiz” checklists, SAY, Lucid Meetings, etc.)
7. cheatsheet (mtl.how/data, mtl.how/sim, mtl.how/facilitate, OSF, etc?)
8. video (determine which...)

[dlkibbe]

@branscombj didn't you do some work on a table of contents for a manual? This is in response to @lzim comment above "Requirement 2) Table of Contents - Finalize inventory all the existing documentation that should be included and create decision rules for a) when documentation is needed, and b) what type of documentation is needed (e.g., manual, guide, checklist, SOP, map, cheat sheet, video, trainings, etc)."

[branscombj]

@dlkibbe yes, but apparently I was a year or two ahead of the game 🤷‍♀ . I will follow the lead of @anthonycpichardo et al in this thread as needed.

[lzim]

@dlkibbe yes, but apparently I was a year or two ahead of the game 🤷‍♀ . I will follow the lead of @anthonycpichardo et al in this thread as needed.

I didn’t know you had a Team PSD TOC @branscombj only an MTL one, right?

If you have one for Team PSD that may be helpful, but our processes have significantly evolved and our resources have been updated.

[lzim]

@staceypark and @jamesmrollins

We talked about strategies for self-directed (asynchronous) learning with learning checks to asses a) competence, and b) confidence for independent contributions in TECH SUPPORT roles.

• The goal is to standardized training resources in the larger Team PSD Manual
• And, an important goal is to free up Stacey and James (and other Team PSD members') time.
• This includes running through scenarios and scripts.
• Clear instructions for skills that haven't been used in some time.

[ritahitching]

List of resources that I found on GitHub that may be useful to add to the TeamPSD Bookdown manual There are likely others on our shared drive.

cheatsheets	facilitate_cheatsheet.pdf
	mtl_how_data_cheatsheet.pdf
	mtl_how_live_cheatsheet.pdf
	mtl_how_osf_cheatsheet.pdf
	mtl_how_sim_cheatsheet.pdf
citation	citation.pdf
listening	README.md
maps	documentation_map.pdf
	mtl.how_map.pdf
	zenhub_flow.pdf
r	errors_fixes	rqda_gui.md
		source compiling_mac.md
	ggplot2	README.md
	packages	Rpackage_status.R
		packages_status.xlsx
	rmarkdown_guides	markdown-cheatsheet-2.0.pdf
		rmarkdown-reference.pdf
	README.md
training_guides	emails_outlook	scheduling_outlook.md
	mtl_how_demo	tt_teampsd.md
		course_code.md
		model_parameters.md
	mtl_how_facilitate	epicenter_admin	admin_web_page_overview.md
			group_management.md
			readme.md
	mtl_demo_admin	Readme.md
		Team_PSD_Webmaster.md
	pldr_admin	readme.md
	teampsd_admin	readme.md
		training_outline.md
		README.md
		mtl_github_sop
	mtl_how_live	guest_login.md
		host_login.md
		login.png
	mtl_how_lucid	README.md
		create_new_meetings.md
		meeting_facilitation.md
		rsvp.md
	mtl_how_osf	osf_project_registration.md
	mtl_how_sim	README.md
	r	markdown.md
	redcap	va_redcap.md
	README.md
	teampsd_emails.md
	teampsd_guiding_principles.md
	training_guide_template.md

[lzim]

@ritahitching

Decided at #hqhuddle on 3/30/2020

1. Begin to organize the public-facing Team PSD resources already online according to Lindsey's TOC above (A, B, C, the order 1...8)
2. Include the links to these public-facing resources.
3. Wait on any resources that aren't already available online

Future Steps

• Review the document_teams column for resources that still need to be finalized.

FYI: @staceypark and @anthonycpichardo

[ritahitching]

I began to organize the Team PSD public resources into the TOC sections

A. Project Management B. Operations (our team will continue to use “Processes” and “Platforms” instead of operations C. Product Management (our team uses “Resources” instead of product).

Do we want a consistent set of subsections within A, B and C to include:

1. SOP
2. Map
3. Guides
4. Trainings
5. Testing
6. Checklists
7. Cheatsheets
8. Videos

Or does it make more sense that each section has tailored set of subheadings?

thanks 👍

Team PSD Project Management	Team PSD Processes and Platforms	Team PSD Resources
Active Listening	Email Policy	Admin TeamPSD
checklists	GitHub Documentation & Issue Cards	Citation Guide Markdown
evaluation	github	Creating Gifs
Lucidmeetings	Data Access
markdown	Data Access 2
MTL Live Instructions	Demo Admin
help_text	Scheduling Appointments	Epicenter Admin
training_guides	manual	tt_teampsd.md		ZenHub	Graphics
	Guides Markdown
	Installation of R package
	Managing Error Messages in R
mtl_menu		Markdown Guides for R
	Model Basics
pre_post_emails
quad_charts		OSF Project Registration
TeamPSD Principles		PLDR_Basics
		Plots in R ggplot2
		RedCap
		Sim Avatar
		Sop
		Version R

[ritahitching]

@staceypark @anthonycpichardo @jamesmrollins @jessfroe @lijenn do your respective workgroups have specific resources that would be helpful to add to the Team PSD Manual, that I have not already included in the table above? thanks!

[anthonycpichardo]

A. Orientation to Team PSD Project Management

• Team PSD Workgroups & Responsibilities (org chart)
• Use of Team PSD meetings and huddles
• A large part of the Team PSD SOP

B. Orientation to Team PSD Processes & Platforms

• SOPs that reflect Daily Workflow processes in including ZenHub Epics, etc.
• Team PSD Platforms & when to use them for key tasks

C. Orientation to Team PSD Resources

• SOPs that reflect testing FAST & SLOW
• Trainings and documentation for Redcap, Data UI, Splashpage, MTL Sim UI, etc.

With regards to the 3 sections outlined here, we (@staceypark , @jamesmrollins , and myself) were thinking it could make sense to Include the Project management section in B. and have A. Be an orientation to Team PSD.

Thoughts? @lzim.

[lzim]

@ritahitching

1. Please note that this is the Team PSD Manual NOT the MTL Manual.

   • For example, nearly all of your Column A will need to be removed because they reference _MTL Facilitator focused” items that are appropriate to the MTL Manual and not the Team PSD focused section A I described in my draft Table of Contents (TOC).

2. Note: Your column headers should use Our Team PSD language that I outlined originally above, providing a crosswalk between traditional roles first, (which are the headers you used), followed in bold by the terms that we use in Team PSD: Orientation to... A. Team PSD Project Management B. Team PSD Processes and Platforms C. Team PSD Resources

@anthonycpichardo @staceypark @jamesmrollins Re:

With regards to the 3 sections outlined here, we (@staceypark , @jamesmrollins , and myself) were thinking it could make sense to Include the Project management section in B. and have A. Be an orientation to Team PSD.

• I’m happy to hear your rationale, but we may be on the same page already, if you read what I’d like to see in “A”

The first thing everyone needs orientation to is “Who does what?” which described in the first two bullets of Section A (i.g. the Team PSD org chart and workgroups):

• People are hired in to specific workgroups with specific position description (PD) roles and responsibilities that they have to fulfill in/out of our regularly scheduled team or workgroup meetings.
• Then, the third bullet adds to the “Who does what?” the “Why?” (SOPs - the highest level overview of how the workgroups and their respective meetings are organized)

A. Orientation to Team PSD Project Management

• Team PSD Workgroups & Responsibilities (org chart)
• Use of Team PSD meetings and huddles
• A large part of the Team PSD SOP

After that we are able to to explain How? we work in greater detail that fits in to the big picture described in A.

• B explains how to work day by day and use the online platforms to manage all workflow processes.
• C provides even greater orientation to training resources, etc. but every training may not be needed by every team member

In other words, I am suggesting that the manual move from the broadest most orienting information to narrowest detailed resources, i.e., the upside down pyramid we discussed.

Does that make sense?

[ritahitching]

• [x] Update table with existing TeamPSD Manual resources to remove all resources associated with MTL Facilitate
• [x] Column headers changed to reflect A. Team PSD Project Management B. Team PSD Processes and Platforms C. Team PSD Resources

from @lzim Please note that this is the Team PSD Manual NOT the MTL Manual. For example, nearly all of your Column A will need to be removed because they reference _MTL Facilitator focused” items that are appropriate to the MTL Manual and not the Team PSD focused section A I described in my draft Table of Contents (TOC). Note: Your column headers should use Our Team PSD language that I outlined originally above, providing a crosswalk between traditional roles first, (which are the headers you used), followed in bold by the terms that we use in Team PSD: Orientation to... A. Team PSD Project Management B. Team PSD Processes and Platforms C. Team PSD Resources

[ritahitching]

@ritahitching to update the table

Definitions & Examples

Team PSD Project Management

• Org chart, who we are, what we do

Team PSD Processes and Platforms

• Specific processes and platforms
• e.g. Lucidmeeting etc.

Team PSD Resources

• Additional information
  • Sending an email

---

• [ ] Split out content within folders that may have .md files that belong in more than 1 column
• [ ] Ask for clarification if the .md file does not seem to have a clear allocation to a column
• [ ] Explain reasoning for choice of allocation of each .md file if relevant

[lzim]

@ritahitching discussed at #hqhuddle 4/15/2020

DECISIONS and NEXT STEPS:

1. @ritahitching read carefully again to better understand how this Team PSD Manual is going to be organized (the upside down pyramid): a. Need to get to a granular enough level that the link is matched to the correct column. b. If/when there are questions, you can list out your rationale for where it would be located for team review.

2. @anthonycpichardo will work on the knitting of the bookdown - by Monday 4/20/20 OUR GOAL: Is not an exhaustive list every resource, get it this knitted AND closing any remaining "master document cards" in the document tracker.

Examples of decision rules: A. Team PSD Project Management - Organizational Chart -Who does What (Workgroups, Roles & Responsibilities, Partners and when they meet )? The broadest understanding of Team PSD (The "Who" of our SOP and mtl.how/teams).

B. Team PSD Processes and Platforms - _Parts of the SOP that describe the "how" of doing things

C. Team PSD Resources - mtl.how/documents document_team dissemintate_scientists_va

[ritahitching]

@anthonycpichardo please see updated cross table below.

Need to decide on the following examples (e.g. should appear in more than one column)

1. In mtl_facilitate_workgroup there are several files that are oriented to Facilitators may be useful to Team PSD Processes and Platforms

   • [ ] glossary (includes values of MTL and TeamPSD e.g. transparency & participatory)
   • [ ] mtl_menu and server.R (includes details why TeamPSD uses GitHub e.g. open source)

2. In resources there are maps and files that may be relevant to Processes and Platforms and also Team PSD Resources

   • [ ] guides for OSF guide on OSF projects may also be useful for disseminate /Co-Is
   • [ ] guides for lucid meetings guide to joining a Lucidmeeting may also be relevant to other partners / scientists
   • [ ] citation guidelines guide on how to cite references may also be relevant to Co-Is

Team PSD Project Management	Team PSD Processes and Platforms	Team PSD Resources
Org. chart - Who does What overview Team PSD	Parts of the SOP that describe the "how" of doing things	mtl.howdocuments document_team dissemintate_scientists
mtl.how	Email Policy	mtl_how_osf_cheatsheet
mtl.how/team	github documentation	OSF Project Registration
Employee Education System Workgroup monthly	various github training guides	documentation_map
Veterans Advisory Partnership for Operations Research (VAPOR) monthly	Data Access	Different grants
Co-Investigator Workgroup meet monthly	Data Access 2 for r	mtl documents
HQ Workgroup weekly	Guides on Epicenter Admin	mtl manuscripts
Facilitate Workgroup weekly	General Guides Markdown
Model Workgroup weekly	Installation of R package
Qualitative Workgroup weekly	Managing Error Messages in R
Quantitative Workgroup weekly	Active Listening
Simulation User Interface Workgroup weekly	Lucidmeetings user guides
National Center for PTSD	markdown guides
Office of Mental Health & Suicide Prevention	MTL Live Instructions
Health Economics Resource Center (HERC)	training_guides
Program Evaluation Resource Center (PERC)	pre_post_emails_mtl_red_blue
MIRECC	TeamPSD Principles
	citation.pdf
	listening
	errors_fixes
	ggplot2 in r
	r packages
	r markdown_guides
	r studio version
	r markdown-reference sheet
	r markdown-cheatsheet 2
	r markdown rstudio
	emails_outloo
	admin guide for epicenter
	epicenter_admin
	epicenter admin_web_page_overview
	epicenter_group_management
	epicenter Team PSD web admin
	Epicenter MTL demo admin
	mtl_how_live_cheatsheet
	r studio fixes
	For rstudio source compiling_mac
	Rpackage_status
	markdown cheatsheet for rstudio
	syntax reference guide for studio
	schedulingoutlook
	tt_teampsd
	Epicenter MTL demo
	teampsd epicenter training check
	mtl live guest log in
	mtl host log in
	lucid meetings pdf user guide
	lucid meetings training check
	meeting facilitation
	off project registration
	markdown language
	VA RedCap training and links
	team psd training guide templates
	team psd guiding principles
	team psd email principles
	teampsd_guiding_principles
	training guide check template
	Epicenter admin over view
	Epicenter team psd group
	creating & uploading gifs
	zenhub_flow
	documenation_map

[lzim]

Discussed at #hqhuddle on 4/17/2020

@ritahitching Question: Where should we put resources that describe Team PSD values

DECISION related to the items below are that Team PSD Values are in the broadest category of orientation, and therefore Rita will update Column A in the Table to reflect this: "Who does what and why"

1. In mtl_facilitate_workgroup there are several files that are oriented to Facilitators may be useful to Team PSD Processes and Platforms

• [ ] glossary (includes values of MTL and TeamPSD e.g. transparency & participatory)
• [ ] mtl_menu (includes details why TeamPSD uses GitHub e.g. open source)
• [ ] server.R

[lzim]

Discussed at #hqhuddle on 4/17/2020

@ritahitching Question: Are these files below so in-depth that they are "Resources?"

DECISION related to the items below are that Commonly used Team PSD Platforms and are not particularly in-depth, therefore they stay in Column B.

2. In resources there are maps and files that may be relevant to Processes and Platforms and also Team PSD Resources

• [ ] guides for OSF guide on OSF projects may also be useful for disseminate /Co-Is
• [ ] guides for lucid meetings guide to joining a Lucidmeeting may also be relevant to other partners / scientists
• [ ] citation guidelines guide on how to cite references may also be relevant to Co-Is

[ritahitching]

Updates to the table, processes use by the majority of team members (ZenHub, GitHub, run meetings) belong to columns A, and more specific examples to be used in Column C, by COB 4/17.

[ritahitching]

• [ ] Cross reference #1220 Develop Master Cross Walk
• [ ] Cross reference #1364 Bookdown style guide for headers
• [ ] Cross reference #1378 Team PSD Issues/Bug/Features template checklist

Team PSD Project Management	Team PSD Processes and Platforms	Team PSD Resources
Who does what and why	Parts of the SOP that describe the "how" of doing things	mtl.how./documents document_team dissemintate_scientists
Co-Investigator Workgroup meet monthly	Active Listening	Epicenter admin add course code
Employee Education System Workgroup monthly	Citation guide	Epicenter admin guide
Facilitate Workgroup weekly	Email Policy	Epicenter admin web overview
Health Economics Resource Center (HERC)	GitHub create file	Epicenter data access
HQ Workgroup weekly	GitHub creating an issue	Epicenter group management
Model Workgroup weekly	GitHub documentation	Epicenter MTL demo admin
Quantitative Workgroup weekly	GitHub guide	Epicenter MTL demo dministration web page (TEST) Login
Qualitative Workgroup weekly	GitHub issues and trackers	Epicenter MTL demo web page (TEST)
Simulation User Interface Workgroup weekly	GitHub labels	Epicenter sign in
Veterans Advisory Partnership for Operations Research (VAPOR) monthly	GitHub pull requests conflicts	Epicenter team PSD group
Simulation User Interface for Team of VHA Providers	GitHub pull requests	Epicenter team PSD web admin
National Center for PTSD	GitHub repositories	Epicenter training check
Office of Mental Health & Suicide Prevention	Lucidmeeting facilitation	MTL facilitator dashboard at forio epicenter
MIRECC	Lucidmeeting new user guide	MTL video - accredited self-directed MTL training
Program Evaluation Resource Center (PERC)	Adobe Connect Room	R package status
Team PSD why GitHub, R markdown	ZenHub flow	R studio current version
Team PSD Guiding Principles	MTL videos on YouTube	R studio errors fixes
Publications & Presentations on MTL by Team PSD	MTL Adobe Connect guest log in	R studio fixes
MTL and Team PSD Lead - Lindsey Zimmerman, PhD	MTL Adobe Connect Live cheatsheet	R studio general guides markdown
	Adobe Connect host log in	R studio ggplot2 in r
	MTL GitHub Repository of Resources	R studio markdown cheatsheet
	OSF project registration cheatsheet	R studio markdown language
	OSF project registration	R studio markdown reference guide
	Training main folder guides	R studio package installation
		R studio packages
		R studio source compiling_mac
		R studio syntax reference
		R studio version
		R sudio managing error messages
		Scheduling outlook
		Shinny library
		Shiny server
		Simulation user interface for team of VHA providers
		Team data user interface - internal for VHA providers only
		Team PSD creating & uploading gifs
		TT report template
		VA RedCap training and links
		Various grants

[anthonycpichardo]

@lzim @staceypark @lijenn @ritahitching @jamesmrollins @branscombj @anazariz Bookdown First Draft Knit index.zip

The zip above contains the first draft of the Team PSD Bookdown.

Things to note:

• Bookdown only supports .MD or .RMD files. So any documentation we want to include needs to be in this format. Meaning any maps or anything else that is not currently in markdown that we would like to include will need to be added to a markdown document.
• The top of every page needs an H1 tag for the title of the chapter.
• YAML headers are not allowed in the markdown document. This means that any documents that we are pulling from GitHub need to have their headers removed before they can be knit. This process can be automated by me
• When listing links from github it needs to be the raw version of the document or it will not be processed correctly. For this draft I built a tool that will download the raw files from Github that have been read from the table @ritahitching put together, I can share the code for this
• .MD files are not read automatically they need to be explicitly told to be compiled by the bookdown tool, whereas .RMD files are read automatically. I can create a script to update the file that dictates which files are read
• Any content we would like to add can be written and included in additional .md files to provide context for the assortment of resources we're including in the book.

I will upload the code I used to compile this current bookdown draft to Github and include the file location here once I have cleaned up the project and provided clear instructions for folks on how to use it.

Please let me know if you have any questions! Next Steps that I may need help with:

• [ ] Upload finished R code to github - @anthonycpichardo
• [ ] Create Markdown documents for any resources we want to include that are not currently in Markdown (i.e: lucidchart maps) @lijenn
• [ ] Create Markdown documents that introduce sections. 1 for each section. @ritahitching
• [ ] Create finalized list of .md or .rmd files to create bookdown. Format for the final table would be similar to the above but utilize the raw url for the Markdown documents and only include .rmd or .md files. - @ritahitching

[lzim]

Cross-ref #1351 - @ritahitching will add a) Team PSD weekly schedule to Column A, and b) Pre-approval email policy to Column C.

[lzim]

Found this YAML fieldguide @anthonycpichardo https://cran.r-project.org/web/packages/ymlthis/vignettes/yaml-fieldguide.html

Did you knit on Monday? Where do we check this out?

[lzim]

@anthonycpichardo briefly touched base on Teams about this today 4/22/2020

• I was able to open the index.zip .html file for the manual, but the TOC didn't hyperlink to the section of the bookdown, like I would expect.

• For next steps @anthonycpichardo is going to come up with a checklist of tasks to review and ask @lijenn and @ritahitching to help.

Thanks all! 🌺

[staceypark]

Decision @ 4/23 HQ Workgroup meeting: @anthonycpichardo @ritahitching @lijenn

Goal: Have a clean TeamPSD manual as early in the May epic as possible

1. 1192 will be in the ZenHub Pipline "Open Documents" as a master document card AND it will be the Team PSD manual in the document_team column.

2. Anthony will split off the already story points as an issue task card that get's completed.

3. Anthony will split the points for figuring out to host the Bookdown Team PSD manual on the Team PSD GH repo.

4. The "original" Team PSD manual content can be edited/reviewed using pull requests.

   a. NEXT STEP: 

   • Rita & Jenn will divvy up review of the specific documents that are in the manual (between Rita, Jenn, Jane, & Debbie).

   b.  Checklist for how to review existing resources to conform to a consistent TeamPSD style and standard use of Markdown for the manual (Rita will create the task card)

   • Define how to use a Level 1-5 headers in a standard way

   • YAML will be removed when knitted and Level 1 Header needs to be the first item in each of the documents

   c. NOTE: Consitent w/the #hqhuddle week of 4/20/2020 we'll keep YAML headers in the GitHub original source material, they are removed when knitting using .Rmd 

   d. Team PSD members can use an RProject for knitting "teampsd_bookdown.rproj"

   e. Ultimately, we we also add the bookdown RProject to Team PSD in "teampsd_manual" folder.

5. Anthony will create an SOP & Checklist for using the RProject and Knitting the .Rmd (to be done in parallel while folks are reviewing existing resources for consistent style in Step 4b.)

   a. update the original manual resource using Pull Request b. re-knit once the update is complete using the RProject

6. Anthony will create document cards in the document_teams column of the document_tracker for creating R & SQL style guides for the TeamPSD Manual.

7. Rita will create a document card in the disseminate_scientists_va column of the document_tracker for style guides (.md) for OSF for specific types of scientific journals - starting American Medical Association (AMA) & APA.

Guide will define: YAML header of the .md file

• Heading levels allowed

• Tables and Figures

• .csl citation language used for the manuscript.

[lijenn]

@anthonycpichardo markdown files of current lucidchart maps that were already in the repo have been made and can be found here: https://github.com/lzim/teampsd/tree/master/resources/maps/maps_markdown

[anthonycpichardo]

Hi! @lzim @staceypark @ritahitching @lijenn @anazariz @jamesmrollins @branscombj

Looking for ideas on how we should handle resources that would be great to include in the bookdown but are not easily added to a markdown document like html pages. I'm thinking about mtl.how/team in particular, but I imagine there could be a few other pieces of documentation with this fault.

My suggestion for a partial solution for mtl.how/team would be to compile the bios we have on github in a master_bio.md file, but I'm open to hearing other ideas.

Thanks!

[lzim]

Hi! @lzim @staceypark @ritahitching @lijenn @anazariz @jamesmrollins @branscombj

Looking for ideas on how we should handle resources that would be great to include in the bookdown but are not easily added to a markdown document like html pages. I'm thinking about mtl.how/team in particular, but I imagine there could be a few other pieces of documentation with this fault.

My suggestion for a partial solution for mtl.how/team would be to compile the bios we have on github in a master_bio.md file, but I'm open to hearing other ideas.

Thanks!

@anthonycpichardo - Are you proposing that we compile in a way that further orients beyond what mtl.how/team does already?

• Consistent with Column A goals of the manual, I think it is helpful to see everyone and their role by workgroup when you join Team PSD.

• But, unless it’s a super light lift 💪 I wouldn’t want to replicate something that is 100% redundant with what is already available at the website, I would only want to compile if there is an additional value provided in the Team PSD Manual.

• But, perhaps I’m not fully understanding what you mean? 🤔

• What do others think?

[anthonycpichardo]

@anthonycpichardo - Are you proposing that we compile in a way that further orients beyond what mtl.how/team does already?

Only if it's something we want to include in the bookdown. A URL to the page could be sufficient for people to access the information.

• Consistent with Column A goals of the manual, I think it is helpful to see everyone and their role by workgroup when you join Team PSD.
• But, unless it’s a super light lift 💪 I wouldn’t want to replicate something that is 100% redundant with what is already available at the website, I would only want to compile if there is an additional value provided in the Team PSD Manual.
• But, perhaps I’m not fully understanding what you mean? 🤔
• What do others think?

I agree that it is a fair chunk of work for not a lot of value gain relative to just having a link to the resource.

Open to hearing more ideas.

[ritahitching]

Cross referencing

• [ ] Issue #1364 Due 5/15 task Team PSD Bookdown Manual: Define header level standards & checklist for review of online resources
• [ ] Issue #1362 Due 5/15 Task: Create a .md and YAML Header Style guide for Manuscripts#1362

FYI @lijenn @staceypark @anthonycpichardo @lzim

[lzim]

Discussed very briefly at #hqhuddle 4/24:

• Lindsey put two potential Org Chart examples that show could show how Team PSD members relate to one another across workgroups in our team Lucid Charts account.
• This would do something that the bios and workgroup breakdown at mtl.how/team does not.
• @anthonycpichardo is going to check it out.

[lzim]

Team GitHub Repos **Cross-ref

1192

1220**

Lindsey will put this together with visual icons for Team PSD Values and Team PSD Principles.

It would be great to get a Visual Map that also shows how these go together.

Team PSD Scientific Values guide additional Participatory and Open Science principles:

• Participatory Research encourages us to co-create our scientific research. Therefore...
• We share decisions, which requires a high level of documentation.
• We seek greater equity among partners in how collaborate, which requires responsive pivots with new stakeholder inputs.
• We strive use transparent and accessible processes and platforms, and develop transparent, accessible resources.

Team PSD Project Management Principles

• NOTE: Team PSD Scientific Values guide how and why we synthesize the approaches below

Team PSD integrates Waterfall principles because:

• We are a research team that cannot deviate in quality, scope, timeline or cost from our thoroughly developed and vetted research plan
• Therefore, there are several well-defined scientific requirements where change cannot occur - unless the PI and co-I senior scientists advise an operational definition or implementation detail is within the scope of the federally funded and registered, scientifically peer-reviewed, and VA ORD and Stanford IRB reviewed procedures.

Team PSD integrates Agile principles because:

• Our research team’s method is a an implementation of participatory system dynamics in a national production environment.
• These methods historically have iterated in-person locally.
• Our innovation is local priorities, local data and local insights at national scale, made possible using online platforms and virtual processes.

Team PSD integrates Waterfall and Agile principles because:

• We are using a funded a priori research design (Waterfall) to study an implementation science (Agile) problem.
• Producing generalizable knowledge requires implementation scientists to follow and report publicly progress completing a rigorous, replicable plan (Waterfall)
• However, the context is not a tightly controlled laboratory, rather we are working with operational partners to implement our innovation the dynamic context of real world healthcare operations (Agile)

Team PSD integrates Lean principles because:

• Team PSD processes are assessed for continuous improvement (kaizen/muda elimination)
• Team PSD communication is designed to reduce rework (muda/waste)
• Team PSD encourages minimum viable products to find and synthesize team and partner expertise (just-in-time)
• Team PSD platforms are designed to increase visual production controls (kanban/signboard; andon alerts)
• Note: VA uses Lean as a primary approach to healthcare quality improvement.

Team PSD integrates Scrum principles because:

• We need to be able keep work produced by our transdisciplinary research team on the same page with our cross-functional team.
• Therefore, we use sprints (epics/milestones)so that the team priorities can be aligned/re-aligned efficiently.
• We also use workgroup leads (scrum masters), workgroups (owners) and workgroup meetings to benefit from the efficiency of divvying up/delegating, while also identifying dependencies and remove blocks.
• We use GitHub/ZenHub and daily huddles to assign, scope, prioritize, manage and review our capacity, requirements, estimates - this includes Project Kanbans, Issue Cards, Pipelines & Reporting.

Team PSD Pain points we are working to better address:

• Need &&tight collaboration without unnecessary overhead, so culture of participation** is maintained
• Need rapid iterations that prototype, check early, and synthesize inputfrom key stakeholders as efficiently as possible, so we aren’t pulled in wasteful directions or adding unnecessary rework
• Need a standard set of principles and processes, so our production platforms are stable at scale.

Continuous Collaborative Iteration Cycles (e.g., “DevOps”)

• SOP > Workgroup Meetings > Monthly Priorities > Requirements gathering standardization for features
• Tools for team members to understand cross-functional “stakes” efficiently
• “Continuous integration” to avoid “merge conflicts” - Quotes are meant to clarify that we have this problem at a communication and conceptual level, not just a code level. We need the code level next...because...
• Ideally...testing, deploying and documenting would be increasingly automated.
• REALLY need continuous documentation and training.

VA GitHub Repo

• May move our Repo here over time....
• See if we have or can get Git on any machines (didn’t used to be able to, but maybe can now)

Ad Hoc vets.gov - benefits tracking NICE Examples for #1220 https://github.com/department-of-veterans-affairs/vets-website

https://github.com/department-of-veterans-affairs/caseflow

va.gov https://github.com/department-of-veterans-affairs/va.gov-team

NICE Examples for Team PSD Manual: Plain English #1192 https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/platform/working-with-vsp/orientation/repo-guidelines.md

With Maps https://github.com/department-of-veterans-affairs/lighthouse-facilities

Git for Version Control

https://towardsdatascience.com/getting-started-with-git-and-github-6fcd0f2d4ac6

https://rogerdudler.github.io/git-guide/

DevOps for Automating Team Dependency Flows and Reducing Errors and Rework

• Develop code tests
• Automated deployment
• Automated testing of pull requests for code review

[lzim]

Morning @ritahitching @branscombj @dlkibbe @lijenn ☕

The *task card #1364 doesn’t follow the TOC of #1192, unless you would like to make recommendations to further reorganize the manual for the team to consider (??). 📖

• Also, we confirmed in our SOP that recording detail TASK card (which will be closed) is problematic for verifying the #1192 requirements for the master document card in one place.
• So, I’m posting this here directly on #1192.

Unless you are recommending a re-org, the 3 main sections of the manual excerpted below would all be the same header level (as they are in my original TOC, and as column headers in the Table that we’ve been reviewing to go with the TOC on #1192)

• That is was I showed in my example above as well from 3 days ago, these 3 main section would likely H2 if the title “*Team PSD Manual” is H1.**
• NOTE: However, my question for @anthonycpichardo about this, is whether this list should actually all be H1 based on how the Bookdown knit works - can you let us know? A. Project Management B. Processes & Platforms C. Resources

Then, we what need, as I said in my comment above was Team PSD Sspecific rules for organizing any manual document in the same way. —- REMINDER: The problem this task is meant to solve is that the documents being knit together in the manual all apply the H1-H6 headers in their own unique ways “as needed” (like your table says) and there is no guidance available to define how they should be applied so the Team PSD manual is effective for learners.

• So, @ritahitching using my example above, what would define the effective standard use of sub headers across all the documents in the Team PSD Manual.
• I think @branscombj and @dlkibbe if you reviewed the documents you would easily see what I mean, and could make recommendations that would standardize.
• We started with headers, but once that’s sorted out, we can also add standard icons or other visual standards that will make the manual easy to use. —-

To provide even more detail that my example above, would the order be:

• H1 Team PSD [depending on Anthony’s answer]
• H2 Project Management or Processes and Platforms or Resources (would it say this? Or would it be broken down by organize the information effectively within the column)
• H3 All Team PSD vs **Facilitate Workgroup vs....(etc but this would be Workgroup level)
• H4 Overall Flow maps for what we’re talking about
• H5 Checklists

Team PSD Manual | Top of document | 1 max -- | -- | -- | — H2 | Medium | ## | Team PSD Project Management | H3 | Small | ### | Team PSD Processes & Platforms | H4 | Smaller | #### | Team PSD Resources |

I’m also not sure that we need any columns that describe what Header and Subheaders generally are (e.g., “smaller”), just the Team PSD rules that we can use to clean up the manual documents so that they can be reviewed, trained on, and understood all together as a book (manual).

[lijenn]

Update: TeamPSD Bookdown is undergoing a prototype version through GH Actions. Discussion is through Teams in the design_teampsd_2.0 channel.

[lijenn]

Hi @anthonycpichardo, I've complied a list of all possible resources to be included in the TeamPSD 2.0 Manual Bookdown to be moved from the Resources folder into the GH-pages branch.

I've separated files into a list for resources and training guides. Note: training guides are located within the resources folder.

I've included the folder that the file(s) is in as that could bring some ideas on how we could organize these files down the road, but we can discuss that afterwards. Then I've included the title of the resource/training guide and the file name/location itself.

Let me know if anything is needed to be edited from this list. Thank you!

---

Resources List from lzim/teampsd/resources

Folder: cheatsheets

• mtl.how/live Cheatsheet mtl_how_live_cheatsheet.md
• How to check files in/out of OSF mtl_how_osf_cheatsheet.md

Folder: citation

• Citation in Rmarkdown citation.md

Question: Do we want README’s included in Bookdown? Could depend on how we decide to use README’s at Support WG & HQ meeting since some README files are essentially the guides.

Folder: design & design/videos

• TeamPSD 2.0 readme.md
• TeamPSD 2.0 Participatory Learning & Design at Scale readme.md

 Folder: listening

• Active listening is a stance. README.md

  Folder: maps/maps_markdown

• How to Update Documentation Flow Map documentation_map.md
• ZenHub Flow zenhub_flow.md

---

Training Guides from lzim/teampsd/resources/training_guides

Not in specific subfolders, sitting at root of training_guides folder:

• Team PSD Emails teampsd_emails.md
• TeamPSD Guiding Principles teampsd_guiding principles.md
• Insert Title Here training_guide_template.md

 Folder: emails_outlook

• Scheduling Outlook Invitation scheduling_outlook.md
• (Excluding tt_teampsd.md since it sounds more HQ focused)

Folder: gifs

• To create gifs, you need to: gifs.md

 Folder: github

• Facilitate Workgroup README.md (looks similar to github_guide.md, but title is facilitate_workgroup)
• TeamPSD GitHub Guide github_guide.md
• Issues and Trackers Management issues_and_trackers_management.md
• GitHub Labels labels_management.md
• How to Create a New File new_file.md
• Pull Requests and Branches Management pull_requests_and_branches_management.md
• Pull Requests with Conflicts pull_requests_with_conflicts.md
• GitHub Repositories repositories.md

Folder: mtl_how_live

• External Links Needed Guest_login.md
• mtl.how/live Login as Host Host_login.md

Folder: mtl_how_lucid

• Lucid readme README.md

• Edit agenda Add documents meeting_facilitation.md

Folder: mtl_how_osf

• Training Guide: OSF Project (Grant) Registration Osf_project_registration.md

Folder: r

• Markdown Language Markdown.md

Folder: redcap

• VA REDCap va_redcap.md

[dkngenda]

@lijenn As a new team psd member, these are some of the questions (in no particular order) that I think would be helpful to team PSD onboarding

• How do I know which meetings to attend, or which meetings my team members are attending (i.e how do I access team PSD central calendar).
  • Which repositories will I be primarily contributing to ? Is there a general overview of how each repo contributes to the overall team PSD mission?
  • What is a typical a team PSD workflow? Any helpful tips on how I can fit into this workflow.
  • How do I let people know what I am working on?
  • Any tips on preparing for a team PSD meeting?
  • How would I identify dependencies for tasks am working on or dependencies I need to resolve for other tasks to proceed.
  • Is there an OSF-Github workflow for me to follow in contributing manuscript under development.
  • What are team PSD values I should keep in mind?
  • Are there any team PSD accounts I should set up?

[dlkibbe]

@lijenn @branscombj @lzim @staceypark Thanks for creating this amazingly detailed and thorough Team PSD manual. Below are comments on the Team PSD manual. Take or leave as you see fit:

1. Create a separate title page with a Team PSD logo. Spell out PSD on first appearance of the text on the title page. (Right now it appears in Chapter 3). And, sometimes I see "Team PSD" and sometime I see "TeamPSD" with no space. Consistent approach would be ideal.
2. Allow chapter 1 to start in its own tab just like the other chapters
3. Suggested title change for Chapter 2 - How to Use the Team PSD Manual
4. Chapter 2, 2.2 Ctrl + F, 2nd paragraph - suggest very minor edit to word "computer's" instead of use of work "laptop’s" - not everyone will be on a laptop when working.
5. 2.2 Item 1 - I'm wondering if the search language should be made a bit clearer. Like:

   Option 1 - use magnifying glass at topic of page; 
   Option 2 - use Ctrl + F to search the page you are on in the manual 

   Item 3 under 2.2. seems a bit repetitive using the Enter key to move through instances of appearances. Not sure if there should be text in the Ctrl + F explanation that says "scroll back up to the top of your screen for the magnifying glass to appear to complete a search"? Let me know if this doesn't make sense.

6. Chapter 3, 3.2 - Suggest that there is a colon after "Therefore:" and indent the list of 3 items that start with "We..." or make it, "Therefore, Team PSD...Shares... Seeks... Strives..."
7. Chapter 3, 3.3.1 - no hyphen needed in "Open-Source"
8. Chapter 3, 3.3.1 - when we say "We use R" - should there be a reference to the organization that developed or provides the license for "R" - similar to how we might include a citation for use of STATA or SPSS?
9. Chapter 3, 3.3.1 - can we assume that anybody seeing / using this manual would know who is an "HQ member"?
10. There is a lot of use of the word "we" - a minor suggestion to replace some of those "we's" with "Team PSD" so the reader is reminded they are part of Team PSD and the collective "we" is considered a team effort.
11. Chapter 3, 3.3.5.1 - Suggest bolding or putting into a "box" so it stands out for the reader the following statement: "KEY IDEA: Really attend to make sure you understand. Do NOT think about your response when you should be listening."
12. Suggest providing links to websites when a phrase or concept in the manual many not be familiar to a new team member: participatory systems dynamics, active listening, waterfall principles, lean principles, scrum principles, implementation science, etc. If the idea of hyperlinks makes you shutter, I suggest expanding the Glossary, Chapter 7 -- e.g., none of the principles included in the list above are included in the Glossary
13. Chapter 3, 3.4 - The first bullet under Team PSD Pain points needs re-formatting - 2 ampersands and 2 asterisks are showing. Suggest editing the title to "Team PSD Pain points we are working to address" - delete "better"
14. Chapter 3, 3.5 - the text in 3.5.1.1 really should appear in the front matter of the manual
15. Chapter 3, 3.5.3 - suggest to make the left column of the table thinner and the right column wider for easier reading & review
16. Chapter 4 - Perhaps a "Background" section here before getting into 4.1 is in order. a. It might include the phrase: Team PSD has established a monthly process for completing its work. This process enables all team members to complete and track a large volume of complex tasks using a systematic framework.
    b. Readers might ask themselves as they review this section: a. Well if this is 2.0, what did 1.0 entail? or b. What is a sprint vs. an epic or are they the same thing?
17. Chapter 5, 5.2 and Chapter 6, 6.1.1 - the text on that flow maps is TINY! Is there any way these can be clickable link so a viewer can dowload the map or go to a link where they can enlarge the image? (yes I know they can increase the percent on their screen but I'm thinking options are good). Also, having white text on a light blue background is difficult for the eye to discern. Suggest darkening the blue in the 6.1.1 flow map or making the text black.
18. Chapter 5 - after experiencing challenges with Teams as an external partner and hearing about the QIIC's challenges with switching over the Team PSD Teams account from their other accounts, perhaps a "Troubleshooting Teams Technology Issues" section is in order even if it links to the Microsoft Teams resource that is linked earlier in the chapter.
19. I suggest somewhere in the manual including key contact information for HQ team members or at least generic emails that a team member can use to request help on activities in the specific chapters,

[branscombj]

@lijenn @staceypark @dlkibbe

Wow, Debbie, what a careful review you gave! I'm not even finding where to review the manual in scrolling through this issue. (I'll look some more later; need to work on manuscripts first!) One question that I have as a member of TeamPSD - David N mentioned "How do I let others know what I'm working on?" - my question is How do I communicate outside of meetings with individual or multiple TeamPSD colleagues about anything that doesn't pertain to a specific issue or pull request in GitHub? Perhaps that's covered already; it's just an ongoing question for me.

[lzim]

@lijenn

Should @dlkibbe’s Feedback be broken down into small tasks?

Should we close this card? Should the Team PSD manual just be a document_tracker card at this point?