Onboarding checklist for new editors

[acrymble]

I don't think we've ever compiled a list of what needs to happen when we bring a new member of the team on board. I thought I'd try to do that so we can smooth the transition in future. Please add items I've forgotten.

• [ ] Add to Google Group (@acrymble)
• [ ] Add to Google Analytics (@acrymble)
• [ ] Add to Twitter team (@acrymble)
• [ ] Add to Github Repos (@mdlincoln)
• [ ] Add bio to /data/ph_authors.yml, including translations (new person)
• [ ] Add black and white avatar (.png) to /avatars (new person)
• [ ] Add to Skype group (@walshbr)
• [ ] Add blog post welcoming new person (whomever sent invite email)
• [ ] Partner new editor with someone willing to offer mentoring and answer questions (whomever sent the invite email)
• [ ] Have the new editor 'shadow' a lesson through the peer review process with an established editor.

For the new person to do

• [ ] Read all sections of the /contribute pages of the website, including author, reviewer, and editor guidelines
• [ ] Bookmark the /jekyll and /submissions github sites so you can find them easily
• [ ] Read the 'Making Technical Contributions' wiki page: https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions
• [ ] Contribute to one open ticket on the /jekyll github site to make sure you know how to do it and are confident contributing ideas.

Did I miss anything, or are any of those bad ideas?

• [ ]
• [ ]
• [ ]

[arojascastro]

Very good! I can't think of anymore tasks at the moment. I am not sure people see issues unless they are pinned so... @vgayolrs @mariajoafana @jenniferisasi @jamotilla for the Spanish team.

[mdlincoln]

I've been wondering if it would be useful for new team members (and maybe even current team members!) to schedule a live onboarding session via skype & screencasting for the technical aspects of how to submit pull requests, how to add commits to specific branches, how to do reviews, etc?

We've tried to encapsulate much of the technical bits in written documentation, but it's still a difficult process if you have not worked with git and GitHub before. And while I am very happy to provide reviews and answer questions on a case by case basis, I'd like to lift the general GitHub literacy of the team up a bit more so that more team members feel capable of understanding errors and correcting mistakes themselves.

[acrymble]

It might just be a matter of having to add a paragraph to https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions that includes how to add more changes to an existing pull request and why multiple pull requests aren't desirable. Github isn't very intuitive to many people, but I've found those instructions helpful.

[drjwbaker]

@mdlincoln What strikes me about your point is that we editors have a culture of emailing each other created - in roughly equal parts - by being geographically dispersed and by having a culture where the majority of our decisions are captured/versioned in public. It doesn't have to be that way. We could choose to talk and/or IM to discuss little niggles (eg, how to do X on GitHub) but we don't. Adding live onboarding would only make sense - to me - if it was part of a culture (or a commitment to have a culture) where "live" work outside GitHub issues/PRs happens more often: eg - at the risk of blurring work and pleasure - using the increasingly wonderful WhatsApp (Skype is increasingly terrible by comparison) to IM, chat, meet et al as a group - or as sub-groups - of editors. Anyway, I'll stop now as I'm going off Issue..

[walshbr]

I might have appreciated a couple sentences about how to manage GitHub notifications. I had never worked on a collaborative repo as active as ours before joining the group, and the issue thread notifications were a bit overwhelming those first couple days until I figured things out.

[ianmilligan1]

FWIW, I'm on other projects that are heavily GitHub based, and I did a lot of onboarding through in-person sessions w/ incoming people as well as us having a Slack group where people can ping for relatively real-time help.

I can add a few more screenshots to the wiki @acrymble for adding to an existing PR.

[ianmilligan1]

I've added a new section on "The Additional Change" to that https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions.

This is a good walkthrough on basic GitHub. I made it compulsory for my team of RAs one summer. https://swcarpentry.github.io/git-novice/

[alsalin]

I very much second the Slack group brought up above for many reasons, but at the least I think that all of this is awesome. Especially the GitHub walkthroughs that the team approves of since there are several ways to get things done.

[amsichani]

I second the Slack group for emergencies but lets have in mind that is not a panacea. What I 'd like to propose is, from my personal onboarding PH experience, for the new editor to try to perform all the future Github actions/tasks/scenarios as mentioned here (eg. open /comment on an issue with all the trimmings eg assign/label, create a branch or PR, process a PR etc). This could be accomplished within a certain period of time (2-3 weeks), even as a mock exercise. By doing so, we - the new editors - will have a more hands-on experience of all the processes we are currently reading of and we need to perform in the near future. I think this will also give us more confidence and the feeling that we 're following well enough the group - overall it will speed up the integration process, I guess. If agreed, I am happy to create and add a "tasks/actions-list" to the above checklist, using my onboarding experience as a case study.

[mdlincoln]

note to self: create a template checklist from this issue, to go into our wiki

[acrymble]

@amsichani that's a great idea. Can you give us that tasks/actions list?

[amsichani]

Here is an (ongoing) draft task-actions list for new editors: (m mandatory , o optional)

[ communication ]

• [ ] set up a GitHub account (m)

• [ ] set up a twitter account (o)

• [ ] set up a Skype account (m)

• [ ] activate Google groups for PH list (m)

• [ ] write an email to the PH Google group (say hello!) (m)

  [ technical ]

• [ ] contribute to one open ticket on the /jekyll github (m)

• [ ] create and assign to yourself a new ticket on the /jekyll github (m)

• [ ] make a technical contribution on your own , following Instructions (one of the first tech contributions would be to add your bio&photo on the /jekyll github, see @acrymble 's list) (m)

I am going to add items on that list, as my PH involvement progresses. Pleas feel also free to add tasks ;-)

[amsichani]

another issue that still puzzles me and might be good to have it written in a more transparent way: I suspect there is a kind of rotation system (?) for PH members in order to review pull requests , assign issues, e.tc. It would be good to explain this in a more explicit way and to (progressively) give also to the new member a role or the freedom to enter to this procedure.

[acrymble]

@amsichani good question about pull requests. We don't have any rules on this really. Generally speaking if it affects any code or could break the site, I think we tend to ask @mdlincoln for a technical review, since he's the only person at the moment on the technical team.

In terms of issues, they tend to get assigned in an informal way. If you make noise on a topic, you might get volunteered for it. You should always feel empowered to jump into any conversation, even if you disagree. Maybe that needs to be written in this welcome to the team intro?

[amsichani]

I think yes, we should write these things up. Might seem quite natural to many of you by now, but not to a newbie to the PH community

[amsichani]

another question: I saw somewhere mentioning a "twitter bot spreadsheet"- am I missing something here?

[acrymble]

@amsichani The Twitter bot was set up by @walshbr to automatically tweet out lessons from time to time. He can explain that best, but perhaps it should be part of the welcome package as well.

[acrymble]

What about this for a page text for new editors, to be posted to the Wiki?

Welcome

Welcome to the Programming Historian Editorial Board. We're very pleased to have you on our team. We know that joining a new project and getting up to speed can be a challenge. So we've put together this information to help you get up to speed. It includes details of what we will do and a checklist of tasks you should complete, to make sure you know how to perform key tasks. We hope it won't take you very long and that this process will enable you to contribute your ideas and energy to their fullest.

What we will do

Within 2 weeks of your joining, our current team will ensure that you have been granted access to the following services used by the Project Team:

• [ ] Our Google Group email so you can communicate with other editors (@acrymble)
• [ ] Our Google Analytics account for monitoring web traffic (@acrymble)
• [ ] Our Twitter team (@acrymble)
• [ ] Our Github Repository so you can upload materials to the site (@mdlincoln)
• [ ] Our Skype group so that you can participate in our monthly calls (@walshbr)

What you should do

There are a few tasks you will need to perform to make sure you know how to use our system, and also to make sure your details appear on the Project Team page. All of these tasks are encouraged, but some may be optional:

communication

• [ ] set up a GitHub account and inform @mdlincoln of your username (mandatory)
• [ ] set up a twitter account (optional)
• [ ] set up a Skype account and inform @walshbr (mandatory)
• [ ] inform @acrymble of your Google-activated email (mandatory)
• [ ] write an email to the other edutors using the Google group (say hello!) (mandatory)

technical

• [ ] contribute to one open ticket on our github repository (mandatory)
• [ ] create and assign to yourself a new ticket on the github repository to ensure you know how to do this (mandatory)
• [ ] make a technical contribution on your own. This will normally be adding your bio to the /data/ph_authors.yml file, and uploading a square black and white avagar (.png) of yourself to /avatars). You will then submit a pull request for approval so that this bio information can be added to the Project Team page (mandatory)

The Culture of the Project

We encourage all of our editors to contribute to discussions on github or via email, and to civily express their views, even if they disagree with any or all other members. This right to express one's opinions is central to our project.

---

please amend as you see fit.

[walshbr]

@amsichani - yep! That's me. There is a spreadsheet for the twitter bot that should be shared with the Programming Historian group. That spreadsheet contains all the tweets that regularly go out four days a week, and we have to add to it manually with each new lesson we publish.

I'm not 100% sure if something shared to a group like that will be automatically shared to each new member added to it. If you're not seeing it in your google drive let us know? In that same vein, it might make sense to make a short list of shared documents a new editor should be aware of. These at least:

• Twitter spreadsheet
• List of reviewers

[amsichani]

thanks @walshbr for this ! nothing found on my Google Drive so far. Good point about adding the list with the shared docs on the welcome list. Funny, but everyone speaks for this wiki page - should we also have a few explanatory lines for the wiki also? What sort of things we keep there that are not on the GitHub issues or main website? In terms of knowledge infrastructure, I am a bit lost here. I can see eg a list of "editorial roles" there , what is it? Sorry for asking too many things - I am the new editor/devil's advocate.

[acrymble]

Thanks for your comments everyone. I hope I have put them all onto the Wiki (which also explains what the Wiki is for, if you read the front page).

The new page for new editors is here:

https://github.com/programminghistorian/jekyll/wiki/Onboarding-Checklist-for-New-Editors

Please amend this as you see fit.