Closed lzim closed 3 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)."
@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.
@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.
@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.
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 | |||
@ritahitching
Decided at #hqhuddle on 3/30/2020
Future Steps
FYI: @staceypark and @anthonycpichardo
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:
Or does it make more sense that each section has tailored set of subheadings?
thanks 👍
@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!
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.
@ritahitching
Please note that this is the Team PSD Manual NOT the MTL Manual.
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?
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 to update the table
Team PSD Project Management
Team PSD Processes and Platforms
Team PSD Resources
@ritahitching discussed at #hqhuddle 4/15/2020
DECISIONS and NEXT STEPS:
@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.
@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
@anthonycpichardo please see updated cross table below.
Need to decide on the following examples (e.g. should appear in more than one column)
In mtl_facilitate_workgroup there are several files that are oriented to Facilitators may be useful to Team PSD Processes and Platforms
In resources there are maps and files that may be relevant to Processes and Platforms and also Team PSD Resources
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"
- In mtl_facilitate_workgroup there are several files that are oriented to Facilitators may be useful to Team PSD Processes and Platforms
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.
- 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
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.
@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:
Cross-ref #1351 - @ritahitching will add a) Team PSD weekly schedule to Column A, and b) Pre-approval email policy to Column C.
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?
@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! 🌺
Decision @ 4/23 HQ Workgroup meeting: @anthonycpichardo @ritahitching @lijenn
Goal: Have a clean TeamPSD manual as early in the May epic as possible
Anthony will split off the already story points as an issue task card that get's completed.
Anthony will split the points for figuring out to host the Bookdown Team PSD manual on the Team PSD GH repo.
The "original" Team PSD manual content can be edited/reviewed using pull requests.
a. NEXT STEP:
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.
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
Anthony will create document cards in the document_teams column of the document_tracker for creating R & SQL style guides for the TeamPSD Manual.
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.
@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
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!
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 - 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.
Cross referencing
FYI @lijenn @staceypark @anthonycpichardo @lzim
Discussed very briefly at #hqhuddle 4/24:
Team GitHub Repos **Cross-ref
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
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).
Update: TeamPSD Bookdown is undergoing a prototype version through GH Actions. Discussion is through Teams in the design_teampsd_2.0 channel.
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
Lucid readme README.md
Edit agenda Add documents meeting_facilitation.md
Folder: mtl_how_osf
Folder: r
Folder: redcap
@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
@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:
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.
@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.
@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?
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
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