Audit phet-info for information beneficial to external users and suggest changes

[brettfiedler]

Transferred from https://github.com/phetsims/community/issues/26

[brettfiedler]

Crossing over the notes here:

phet-info note audit

High level notes

• Checklists have interesting information re: process, but are not very useful for new contributors
• Should intern-info be folded into onboarding? Isn't an intern a new contributor?
  • The information here is largely redudant to the onboarding doc. Check for helpful tips and add to a different document.
• The CLA is in the community repo, doesn't need to be here, possibly. OR, better yet, doesn't need to be in community.
• Doc folder contains most of the useful information
  • Place Inclusive Features Quickstart guides into their own subdirectory
  • These have nice information about using the common code libraries and exemplars for creating inclusive features, but the features themselves are not independent in all cases. They require our tooling (grunt, chipper, etc) to be used, and are not standalone. This is a good thing, but it means that they are not as useful to the community as they could be.
  • ADD: A document with concise instructions for enabling or integrating inclusive features into a web interactive, using a sim as an exemplar if needed.
• The PhET Overview and Onboarding Documents are our primary documents here. We should change weave these together more concisely. Onboarding needs to stay PhET specific, but we can make a different version that is more community facing.

Diagram a la graph on Onboarding Doc

Doc Site

• Oliver on Slack:

  • I wonder if continuing to make phet-info public is the right call… it seems to contain a lot of internal information. If there are things in that repo needed for POSE perhaps a bigger reorganization is needed? (Or a new repo)

• Could choose to keep helpful information in phet-info, and sync across to community docs with https://github.com/marketplace/actions/repo-file-sync-action

Detailed Tree:

(++): Has info that should definitely go to Community (+) : useful as a reference (%) : might be worth a small reference in limited cases, or has information worth extracting null : not useful (--) : not sure why this is here

• checklists: some checklists provide good insight into sim dev process, but not
  • S2015R-checklist.md
  • (%) code-review-checklist.md
  • delete-repo-checklist.md
  • employee-leaving-checklist.md
  • external-library-checklist.md
  • new-repo-checklist.md
  • (%) new-student-worker-checklist.md
  • postmortem-process.md
  • rename-repo-checklist.md
  • (%) sim-checklist.md
  • updating-metadata.md
  • youtube-upload-checklist.md
• conduct
  • (--) communication-guidelines.md: This is very internal and should be moved and/or hidden?
• conferences
  • README.md
  • collect-emails.html: This is an offline form for collecting emails at conferences. Should inquire as to need or if it should live somewhere else. special-ops?
• contributors
  • (++) CLA.md: I have question out regarding this for common code
  • (++) CU PhET Institutional Contributor License Agreement.pdf: I think this is specifically for partnerships, where CU may need to be legally involved.
• deployment-info
  • README.md
  • chipper-1.0.md: helpful only for those doing old JavaScript development
  • (+) chipper-2.0.md: This is specific tooling for simulation development. Very helpful if creating a PhET-like. I believe this will need to be greatly updated when Deno is introduced
• doc
  • (+) accessible-preferences-quickstart-guide.md: requires a preferences menu. Where does pref menu live? Sim-specific, but good practices contained
  • (+) alternative-input-quickstart-guide.md: Good practices, sim-specific and requires our tooling
  • (+) coding-conventions.md: not required for community, but good practices, worth linking
  • BROKEN LINK: best-practice-for-modules.md
  • (--) devs-onboarding-pm-q4-2021.md: This looks old and irrelevant
  • (+) dynamic-string-layout-quickstart.md: Good practices, sim-specific and requires our tooling
  • (+) interactive-description-technical-guide.md: Good practices, sim-specific and requires our tooling
  • (+) interactive-highlights-quickstart-guide.md: Good practices, sim-specific and requires our tooling
  • (++) new-dev-onboarding.md: Good information here, needs that info extracted as a different document.
  • (++) phet-dev-exercises.md: Very helpful reference for those starting to use our libraries for SIM DEVELOPMENT
  • (++) phet-development-overview.md: Key document for using PhET libraries.
  • (+) phet-software-design-patterns.md: Very helpful reference for those starting to use our libraries for SIM DEVELOPMENT
  • (%) supported-browsers.md: This is maybe worth a reference, but specific to our QA process
  • (++) typescript-conventions.md: Key reference for using PhET libraries
  • (++) typescript-quick-start.md: Key reference for using PhET libraries
  • (+) typescript-webstorm-file-watcher.md: specific to webstorm, but useful for those using it
• git-template-dir
  • pre-commit.sh
• github-dashboard
  • issueReport.js
  • processCachedIssues.js
• github-labels
  • README.md
  • change-label.sh
  • delete-label.sh
  • (+) github-labels
  • (+) labeling-scheme.md
  • new-label-all-repos.sh
  • new-repo-add-labels.sh
  • printGithubAuthorization.js
  • update-repos-list.js
• (%) ide: this whole directory may be a nice reference, but is not necessary
  • idea
  • performance.md
  • phet-idea-codestyle.xml
  • setup.md
  • sublime-text
  • phet-plugin
    • files for a sublime package to add phet tasks to command pallete
  • Monokai PhET.tmTheme
  • PhETJavaScript.tmLanguage
  • eslint-and-sublime-text.md
  • vscode
  • setup.md
• (%) intern-info: most of the information here I think is redundant to info in onboarding and overview docs
  • git_bash_tips.md
  • job-postings.md
  • web-dev-intern-setup.md
• (%) issue-info: most of this is related to PhET specific processes, but there should be strong overlap between the issue templates for all repos and this
  • github-issue-philosophy.md
  • unfuddle-ticket-search.md
  • useful_searches.md
• policies: these are very PhET employee and policy internal. Not community facing.
  • Confidentiality-of-user-information.md
  • availability.md
  • team assignment.md
• project-management: This is all outdated and also very interal. Not community facing.
  • common-code-issue-template.md
  • management-granularity-levels.md
  • reportEpicIssuesNotInSpreadsheet.js
• (--) qa-team-info: This is redundant? I did not get a clear answer on Slack
  • Screenshots.md
  • applicant-task.md
• resources
  • (%) screen-reader
  • (%) developer-resources.md
• sim-info This is all very PhET specific. Not community facing.
  • README.md
  • areAllReposInFile.js
  • generateMarkdownOutput.mjs
  • getAllRepos.js
  • pixelzoom-sims.md
  • printReposPerDev.mjs
  • responsible_dev.json
  • responsible_dev.md
• LICENSE
• README.md
• package.json

[brettfiedler]

11 is an emergent issue from this task

[brettfiedler]

Noting discussion in Slack regarding this issue:

KP Does anyone know of any reason why phet-info repo needs to remain public? There is quite a bit in there that would be better to be private, and we should either separate it out or make phet-info private.

BF

At this point I have most of the important SceneryStack related info syncing to another repository under the scenerystack organization. Not all of it, but at some point we would want to modify/differentiate those docs anyway. CM pointed out when I was doing an audit of the phet-info contents that there is a lot of cross referencing in the docs in phet-info and a lot of code points to phet-info links, so we would want to be careful we don't break any connections or leave people with important relevant info they cannot access anymore.

KP How do you recommend proceeding? Should we make a scenerystack-info repo, and move stuff into that? Should we make a phet-info-private repo and move private stuff into that?

BF I can wrap back around at dev meeting next week to gauge the workload and perspectives here, but yeah I think we can codify the scenerystack/community repo for information that is not specific to internal PhET processes, or can be freely made to be non-specific. This includes some of the onboarding tutorialization, development overview, etc. I think it is OK that it is sim-dev specific, to be clear. That is the (only current) focus of the existing community. As it is in the current SS website, we just divide resources for sim dev and more general concepts (e.g., Scenery API doc). I want to get a sense from folks where things like Checklists fall. I do think various checklists (looking at you Code Review checklist) are informative for others creating sims, so I do not want to lock them away in a private repo, but they are obviously very PhET specific. I actually only copy over an "example", trimmed checklist right now, which I copy/pasted from the code review checklist without linking the actual checklist itself. Earlier I had done a (now out of date) audit of phet-info, but I can run through again with new understanding and new documents. I'd love to have the website end up being a resource where the Devs go for information important for code understanding, and phet-info be a place for internal process, and a clear delineation so that no one is confused on where to go. We should also maybe consider where information like the PhET Getting Started Guide live, which we can pretty easily convert to Markdown and put into phet-info, but would need to re-implement the images. See attached markdown document which took me no meaningful time to create.

​ON Side note: Is there a PhET Getting Started Guide in phet-info?? I don’t see a reason to keep phet-info public. The repo contains so much that is meant for our internal team. If there are resources intended to be public, I’d vote to either recreate in a public location or use an automated sync action to a public repo.

BF I don't believe there is. But yeah, I'll connect up with you when I get back from ***** and maybe we can differentiate the docs in phet-info and identify other docs (Google docs or otherwise) that could be moved into a future private phet-info.