lzim / teampsd

Team PSD is using GitHub, R and RMarkdown as part of our free and open science workflow.
GNU General Public License v3.0
9 stars 23 forks source link

Team PSD Manual #1192

Closed lzim closed 3 years ago

lzim commented 4 years ago

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.

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.

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

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
B. Orientation to Team PSD Processes & Platforms
C. Orientation to Team PSD Resources
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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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.

ritahitching commented 4 years ago

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 commented 4 years ago

@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

FYI: @staceypark and @anthonycpichardo

ritahitching commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago
A. Orientation to Team PSD Project Management
B. Orientation to Team PSD Processes & Platforms
C. Orientation to Team PSD Resources

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 commented 4 years ago

@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.

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):

A. Orientation to Team PSD Project Management

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

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 commented 4 years ago

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 commented 4 years ago

@ritahitching to update the table

Definitions & Examples

Team PSD Project Management

Team PSD Processes and Platforms

Team PSD Resources


lzim commented 4 years ago

@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 commented 4 years ago

@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

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 commented 4 years ago

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 commented 4 years ago

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.

  1. In resources there are maps and files that may be relevant to Processes and Platforms and also Team PSD Resources
ritahitching commented 4 years ago

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 commented 4 years ago
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 commented 4 years ago

@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:

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:

lzim commented 4 years ago

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

lzim commented 4 years ago

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 commented 4 years ago

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

Thanks all! 🌺

staceypark commented 4 years ago

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

lijenn commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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?

anthonycpichardo commented 4 years ago

@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 commented 4 years ago

Cross referencing

FYI @lijenn @staceypark @anthonycpichardo @lzim

lzim commented 4 years ago

Discussed very briefly at #hqhuddle 4/24:

lzim commented 4 years ago

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:

Team PSD Project Management Principles

Team PSD integrates Waterfall principles because:

Team PSD integrates Agile principles because:

Team PSD integrates Waterfall and Agile principles because:

Team PSD integrates Lean principles because:

Team PSD integrates Scrum principles because:

Team PSD Pain points we are working to better address:

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

VA GitHub Repo

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

lzim commented 4 years ago

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 (??). 📖

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)

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.

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

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 commented 4 years ago

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

lijenn commented 4 years ago

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

Folder: citation

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

 Folder: listening

  Folder: maps/maps_markdown


Training Guides from lzim/teampsd/resources/training_guides

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

 Folder: emails_outlook

Folder: gifs

 Folder: github

Folder: mtl_how_live

Folder: mtl_how_lucid

Folder: mtl_how_osf

Folder: r

Folder: redcap

dkngenda commented 4 years ago

@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

dlkibbe commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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?