Open sereedmedia opened 1 year ago
sereedmedia
commented
1 year ago Also to include: What permissions to expect at what level of contribution? That way folks won't need to ask or wonder if they should or should not have various permissions.
sereedmedia
commented
1 year ago In terms of where to publish: The Contributor Handbook would make sense, especially in terms of a single source of truth. It could also be part of a Learn course for new contributors. (Or both!)
Also important: Find out what efforts are happening on this issue with other teams around the project so as to not duplicate efforts.
abhansnuk
commented
1 year ago Hi @sereedmedia a one central place to have GitHub help info specific to how the WordPress organization uses repos, boards and tickets is a good idea - You will be glad to hear there has been quite a lot of work done on this and liaison with other teams. GitHub is increasingly having its own beginner and intermediate level user information, rather than teams having to produce as much of their own or update it as often. The Contributor Handbook was highlighted last year to have some of the shared information on using GH that was WP-specific and then with outward links to GH's own documentation.
There are also GH specific issues that affect more than just Marketing and different teams are working on solutions which will benefit all teams. Nalini from the updates in meetings and cards has been doing a lot on this, so I will try not to duplicate on the info added to this ticket.
In terms of 'good first issue': collating more areas where people struggle in GH will be very useful.
More detailed background I have put as much background/ team memory information into this comment as I could tonight. Some I have copied from the GitHub to do list on the wiki pages.
Project boards location issue - wider than Marketing There's some issues on how and where project boards appear in GitHub, and this is currently being looked into for a resolution as it affects more than marketing. The issues behind some of the GitHub difficulties already noted appear to be linked to GH's own changes and beta features, and partly relate to permissions set up at a higher level on project board locations.
A lot of the solutions we had built in marketing with the help of GH power users were not possible when the repo moved from a standalone area to under the WordPress main organizational umbrella. GH seems to be bringing for large organizations some of these features we currently do not have in the Marketing repo.
Solutions for a central help/ how to information tested: a) Easy website view for help information @vimes1984 and @meherbala set up using GitHub tools and add-ons set up an easy view area, which looked like a website, and where help guides could be added. This was populated in a test involving 25 plus people, and acted as a working help area in the interim.
Following liaison with other teams, some of the learning curves faced by Marketing Team members and more so queries on using GitHub were found to be similar across teams, particularly training and documentation.
This is still available if needed, but other solutions already in play across teams may be more suitable and take up less time from a dev.
b) GitHub wiki Last year, an attempt to bring together ideas and solutions on a GitHub wiki was tried. Not all those who wanted to from other teams found it easy to add to a wiki on the Marketing repo. Some marketing contributors found it difficult having a wiki area open in GitHub at the same time as a ticket or discussion ticket.
Nicholas and some other contributors were to explore the wiki solution a bit more. In the meantime, GH also produced some documentation that helped and marketing could signpost.
c) Keeping a WP handbook page on general GitHub usage up-to-date This has been a recurrent issue and led to a lot of time to change screenshots and text as GitHub is expanding and producing its own documentation. It is not sustainable to try and keep up with the changes for standard how-to GH info. It is far better, to point to the tool's own documentation where there is correct and current information, and it is easy to follow.
It can be more useful and effective to focus on how-to info for the specific areas people are finding it difficult to learn when they are new to a particular repo (eg marketing).
Last time there was a practical solution-finding chat on a GH how-to with different teams members, this seemed to be a good solution forward. It also found that some of the areas Marketing Team members seem to be having difficulty is about using GitHub for the first time and setting up an account. Generally we can't link to 3rd party external resources on the P2, but there are some really good how to get started videos already for beginner GH users.
@nalininsbs has been involved in separating what is marketing specific and needs more help, and what of the questions seem to apply to more than one team. I and others in marketing and other teams who use GH tickets and boards across the project as well as in our own work have answered various questions and provided help when she has been assisting others. According to some of the GH tickets comments, she was coming back to these once she had more time in February and finished supporting the 2023 team reps onboarding and set ups.
d) Identifying handbook changes and version control This has been highlighted in a number of teams recently, and there has been discussions about how handbooks could use GitHub better for doing this and to be able to improve / note efforts by contributors. Documentation had a discussion on this again last week or so, and some of the ideas discussed could really help teams like Marketing and Training. This would also help with version control and updates which could be shared across teams on using GitHub specific to the WP repos.
e) Contributor Handbook and its predecessor on GitHub Common questions were being collated to help all teams and help at contributor days/ events.
Due to version control, duplication of effort, and translations workflow and publication issues, a cross-team GitHub repo was set up for this and many of the marketing team helped move it forward.
Through sharing information and solution ideas, the cross-team GitHub Contributor repo in part was to be used/ evolved into the Contributor Handbook and the Contributor Working Group (I can't recall its proper name right now). There is also the revisions plugin for updates that some teams have set up.
Throughout, there have been discussions to support translation and internationalization of whatever system was used for GitHub help documentation within WordPress and for Contributor Handbook.
Much of the documentation that had been put together in Marketing has been superseded by GitHub producing items, and some features are new in beta which Marketing and some other teams have tested / used too. GitHub will probably produce documentation on this too. I know @nalininsbs was working on bringing a lot of this together and there are a couple of GitHub cards on Marketing already about different aspects.
There should be a ticket which captures many of the questions, issues, how to explanations. I remember seeing it update with some links to GitHub's own documentation recently.
Permissions and security Everyone with a GitHub account can comment on a GitHub card in the Marketing repo. They can also ask to assigned to a card/ ticket, and one of the team reps or the repo's support of more advanced GitHub users (Chris, Meher, Abha, Nalini, Nicholas, Larissa, Shanta etc) can assign them once they have added a comment. If they have already been added to the team's GitHub usage, then they can assign themselves. There are two team members' accounts which do not seem to work as they should and there are support requests into GitHub about this already. We discovered and resolved the issue on your account when we collaborated a few weeks ago.
As when I helped you onboard and set up GitHub access, requests to join the Marketing team on GitHub require a confirmation click on the email sent out by GH itself. This seems to be time limited by GH to a few hours, but sometimes emails can take a while to get through to contributors or get stuck in junk filters.
Two-step-verification is also needed for some user levels, and as I understand it, this will be the case for has GitHub WP team access.
GitHub props There is work, led by core, on how this can be done better and which could be used across all the teams once finalized. This will have recommendations about how to add props so that they can be picked up by particular scripts. In Marketing, the person who closed the card was asked to just add a line of props, until the core proposal/ fix came in, and then follow this with any adaptations which were needed.
GitHub spam As GitHub is open to anyone to comment, there have been times when tickets are spammed or new tickets created by spammers. When this happens one of the team reps (you should all have permissions to do this) or the people who have volunteered to provide GitHub support in Marketing can delete the entry. Larissa was able to delete a few in December.
All the team reps' permissions should allow any of you to delete spam comments.
@nalininsbs and others may have more background.
sereedmedia
commented
1 year ago Thank you so much for all of this information @abhansnuk !!!! You're such an incredible wealth of information. <3
nalininsbs
commented
1 year ago I am in progress of trying to merge some of the GitHub meta requests, issues, and WordPress Meta requests into one place. They will be linked from this card. https://github.com/WordPress/Marketing-Team/issues/160 This will take time as some issues have now been solved, though there are a couple of new issues by the resolutions/ changes in GitHub too.
leogopal
commented
1 year ago As Community Team Rep, I have been trying to make a case for the adoption of Github for Project management. See Proposal: https://make.wordpress.org/community/2023/01/19/proposal-adopt-github-for-team-projects/
I am keen to help and follow the progress of this initiative as it will assist not just my proposal but any team wanting to make the transition.
jennimckinnon
commented
1 year ago Commenting here to be kept in the loop (not the WordPress one, but sort of 😄). I'm circling back to offer feedback/suggestions and to finish reading the comments as @sereedmedia mentioned in the Marketing meeting today that this is related to issue #169 that I'm working on.
There are likely many resources for onboarding and contributing to WordPress via GitHub around the project, but it would be great to create a single document/page that all teams could use as a reference point for new contributors. (This could also be used for updating existing contributors on new processes and could include a reference to the Code of Conduct, etc.)
Tasks needed to complete this: