OLS-3 Week 4 Cohort call 2: Tooling and roadmapping for open projects

It is equally fine also to type messages in the chat or questions, and we’ll try and keep an eye on that and answer any questions or thoughts that come through there as well.

00:43 - So on the top left corner of the zoom screen you should see it says live on otter. ai. Click here to open live transcript.

00:52 - This just allows you to follow along. It should try and transcribe what we’re saying so you can follow by text rather than by speech. That’s completely optional. And let me see where we’re at. We’ve got some fantastic icebreakers. Some moods about what’s been going on with people who’ve been joining and how they’ve been finding OLS-3 so exciting busy overwhelmed. I’m sending hugs I feel the overwhelmed, there is there’s too much overwhelmingness right now.

I will have to go and look at the reaction gifts you’ve put in here how later on. But Malvika did indeed give a very winning 10 arguments against Open Science talk yesterday that was absolutely amazing. And yeah, just keep those icebreaker answers coming in and way too into this as a side project, loving it. This is fantastic. I also see a couple of people saying that there are a lot of tools. And yeah, absolutely. We do start with I think a bit of a hurricane of new and exciting things, I don’t think we introduced much radically new after this, this first couple of cohort calls where it’s like, here’s all the things.

But if you ever have questions please pop into the slack, or use email to your mentors or to the organizing team, and we will try and figure out what’s up because we don’t want things to be difficult. We don’t want them to be scary. And it will it will get more comfortable, as we go.

02:26 - Right, we have a code of conduct. So as a general reminder, this means treat one another with respect that you’d like to be treated with when we’re interacting with one another in calls. You can see this on page four, there’s a link to the code of conduct. And if at any point you feel like you’ve either experienced or witnessed behavior that isn’t in line with the code of conduct, then please report this, so you can report this to team at open life sci.

org that’s the group email that reaches myself Malvika and Berenice, or it’s also possible to report individually if there’s a reason that you’d rather not reach the whole team. And so all of our email addresses are over in the code of conduct section on page four. And I said page four, but I think I’m at page five, because the document moves and grows. So I think that the next. Oh, one more thing one more reminder is that we do breakout rooms in the call and some, some breakout rooms can be spoken, and other breakout rooms, these are just small private rooms, out these breakout rooms will be written some of them.

And so it’s fine to you to either choose which one you prefer, but in order to make it easy for us to get you into these rooms. We would ask that you just click on participants on the bottom of your screen I’m using a computer not on mobile here, there may be a way to do it on mobile as well. But click on participants, and then click on your own name and beside your name. There should be a more, and it allows you to rename yourself and just put s, if you prefer spoken for breakout rooms, w if you prefer written, or if you don’t mind just put a S/W for you and that allows us to sort you into each of those different types of rooms so I’m just gonna pause for a minute and just ask everyone to make sure that your name has an S or a W or both beside it now quickly.

And again, if there’s anything that’s unclear, now’s the time to ask them, ask questions.

04:47 - Looking good. Most of us have the Ss and the Ws- fantastic.

04:52 - Right. Thanks everyone. Sure. So what’s next. Oh, one last thing before we have introductions, which is exciting. So, I can see kitty cats. I’m very easily distracted by kitty cats I apologize if sorry for cats, right where was I oh yes cohort name. So folks we had. We’ve been voting on a cohort name and Slack, and I think it’s pretty safe to say based on all the votes that the name for OLS-3 as a cohort is going to be perseverance. So, hello perseverance I am delighted to be working with you for the next few weeks, months, etc.

Okay. Right. So from here on, we will introduce all of our emails and say hello, perseverance, as a cohort. Fantastic name, so thanks for suggesting it I think john suggested it. Next thing introductions, Emmy. Are you good to take us through introductions for anyone who is new this week.

05:55 - Emmy Tsang: Yeah. Hopefully, so can I can I just ask sorry because this is a huge cohort and it’s always lovely lovely to see all of you and have so many people here but it also means that I lose track of who was here last week. If you just, if you haven’t had the chance to join us last two weeks ago, put your name on the agenda, so that we can know who you are, and we’ll go through the verbal introductions quickly as well.

06:23 - So because as you notice there’s quite a few of us so to do this quite efficiently, we asked you to introduce your name, where you are based, your project name, so just the name, not the description and let us know your most recent hobby. So, I’ll just give folks about 10 seconds to put their names on the agenda.

06:45 - We’re on in the middle of page five, I believe, and we’ll go in the order on the agenda, called just waiting for five seconds before So, again, my apologies for the horrible mispronunciation of names in advance, please correct me but Arvinpreet, whenever you’re ready.

07:15 - Arvinpreet: Can you please repeat your question.

07:18 - Emmy Tsang: So just share your name, where you based, what’s your project name and your most recent hobby.

07:25 - Arvinpreet: Okay, my project is on system genomic integration of diabetes related genes, a quest for Developmental biomarkers.

07:37 - This, the whole name of the project. Emmy Tsang: And do you have a recent hobby that you picked up? Or something you Arvinpreet: currently I am revising for my exams as well.

07:54 - So there’s a lot of food in a project as Emmy Tsang: Fantastic thank you And next we have Marzia.

08:04 - Marzia: Yes. Hi, everyone. I’m Martin. I come from Italy. My project name is sitting. Hi, I’m working with Dario.

08:15 - Unknown: And my hobbies harm. Marzia: I love thriller books.

08:22 - Unknown: so Emmy Tsang: fantastic. Next we have john.

08:30 - john: Hi my name is john. I’m from Nigeria. I’m based in the uk. My project is APOL1 variants, finding the global distribution. Essentially, I’ve been forced to learn how to code. That’s what I’m doing now. Thank you.

08:55 - Emmy Tsang: Have you here Hope the coding is going well.

08:58 - Steven. Steven Burgess: Hi everyone, my name is Steven Burgess. I’m currently in Champaign, Illinois in the US. My project is called Open phototrophs. And I’ve recently been playing a lot of board games with my wife.

09:17 - Unknown: that’s Emmy Tsang: great. There’s quite a few board games fans here I believe so can start a separate group. Next we have Aida.

09:30 - Aida: Hi, my name is Aida. I’m based in London. My project is about embedding open source or open Science practices within the newly created team at the Alan Turing Institute in London, and my hobby is parenting because I have a 14 year old toddler.

09:50 - Emmy Tsang: Thank you. And next we have Ali.

09:53 - Ali: Hey guys, Ali. I’m also from London. My project is I’m building a community health report on the Turing Way project, and my hobby. I don’t know if it’s a hobby but I’m really into sports so I’m watching football and basketball and stuff like that these days, while I can with the lockdown here.

10:11 - Emmy Tsang: Thank you. Carlos. Carlos: Hi, my name is Carlos I’m based in Utrecht in the Netherlands. I’m not sure which project they should be talking about because I’m involved in a couple of projects so I just put question marks and recent hobby is running. Yeah, just running a lot more than I was running before so. Yeah. Thank you.

10:38 - Emmy Tsang: And next we have Hao Hao: Hi, I’m Hao I’m based in Gainesville Florida in the United States. I don’t have an OLS project, but I am working on an open grants repository and my most recent hobby is not water over water, my house plants.

11:01 - Emmy Tsang: I share your struggle there. Thanks Hao. I believe that everyone in the agenda has anyone not had a chance to introduce themselves yet. You can let us know in the chat or quickly unmute yourself.

11:21 - Go another five seconds. All right.

11:30 - Name just coming in. Sorry, Prakriti. Do you want to give a short introduction of yourself.

11:41 - Prakriti: Hello, I’m Prakriti Karki, I’m based in Kathmandu, Nepal, and our recent project for the OLS is, is entitled GyaNamuna which is the model of knowledge, and my recent hobby is reading books, and currently I have exams and so I’m preparing for that Emmy Tsang: all the best with exam preparation and, yeah.

12:13 - Books recommendations are always recommended in slack. Awesome.

12:19 - Thank you all. So I think the next section we have a breakout room. I think Malvika is not here yet so I’m going to try and do this.

12:32 - Unknown: So Emmy Tsang: this might be your first breakout room so I’ll go through carefully and make sure we all manage to understand what’s going to happen next. So in the next 10 minutes we will divide you digitally and magically through the powers of zoom into smaller rooms to discuss two questions. So these questions are now put in the zoom chat as well but it’s also on the agenda at the top of, whoops, on the top of page six.

13:02 - And so think about a time you were collaborating or working on an open project, and it was a complete train wreck. What has happened, what made it so chaotic and think of another time. Hopefully, you know, collaborating, or working on an open project, and everything was perfect. What has happened and what has made it sublime. So, we’d like you to in your groups, discuss these questions, share your thoughts and experiences, so that we can all learn from each other as yo was saying at the beginning, we’ve all renamed ourselves with S or for spoken breakout rooms or w four written breakout rooms.

So, in the written rooms, you could write your thoughts down either using the zoom chats, or. We have also sections on the agenda in Page Six where you can just put your, what you want to say directly on the agenda as well, whichever you prefer. And in this spoken rooms, you can just speak. And after 10 minutes, we’ll come back and if we have some time. You can share what we’ve talked about in the smaller groups and you can also read other people’s comments.

14:20 - If you when you’re in the room so in the moment there will be a pop up on your screen that you will be asked to click one button and you enter the room. If you need help, within the breakout room you don’t know what’s happening and you’re confused, press the Ask for help button that’s on the bottom of your zoom menu bar, Is that kind of clear So, Yo are the rooms ready? Yo Yehudi: They are and thank you for stepping in to introduce because I was just finishing the last bits in the rooms.

So if everything is clear, can we have some thumbs up. Awesome. Okay, we have enough thumbs up that I’m confident, I’m going to send you all into the rooms, and don’t forget you have 10 minutes.

15:01 - Have fun. So, aleksandre and nihan, and Arvinpreet, have you seen the pop ups. Okay, Arvinpreet’s gone. Make sure no one’s alone.

15:48 - but I wondered if anyone had anything really interesting, or surprising that you want to share from the discussions that you had. And it’s also kind of put this in chat or read out anything that’s in chat as well, or unmute Either is fine.

16:01 - or unmute Either is fine. I’m not afraid of leaving the awkward silences if necessary.

16:21 - But what I will do, I will just I’m going to scan through what we’ve been writing here so we have some people saying it’s really nice when someone takes control of good housekeeping. As one of the nice things, I can see people saying that when there’s a lack of dialogue or a lack of trust that things don’t go well, or inattention to results can be a problem. Having a leader within a team can be helpful expecting too much of collaborators.

Ouch. Yeah, that can be tough. I wonder if the flip side of that is taking more on than you can do which I know is a problem I definitely that you’re trying to make sure that when you promise to do something it’s something you really can do as a big tough one, some some some good things here I see brainstorming, I see having at least one expert in the team.

17:12 - Some more negatives, our lack of leadership, individual character intent on themselves, that it can be so tough. Yeah.

17:21 - Arvinpreet, I know, I know you mentioned unequal contributions that can be a challenge but I think one thing to notice is that sometimes not everyone has enough time or ability to contribute equally as I guess it’s an equal contributions.

17:36 - When they could, and there’s good reason for them to be equal maybe makes a difference? mismatch communication. Yeah, so I think there’s a lot of ups and downs that are nice to think about when you just sort of read through the notes that everyone’s been fantastically adding to this Google Doc, and maybe just things to think about in your own projects maybe to try and avoid or is a good thing that you want to be keeping on doing. So everyone keep those notes coming in because they are absolutely beautiful.

And I love the way they make me think every single time. So I’m going to move on to the next bit So, today, since we sort of introduced GitHub in a bit of a scary way last time, and we’re going to talk about how one can use GitHub, to, to create a place where people can easily collaborate. And we’re going to talk about a few files that you can put on your GitHub repository that just sort of.

18:29 - I’m really sorry about that. I promise it will get easier and eventually it feels like breathing. But anyway, and some ways to make it easier for people to step into your project when they are joining and way ways to make it make them know how they can help you and how it’s a safe space. So there’s four files, we’re going to talk about today. The first one is the license, this just tells people how the content that you have can be reused.

So what rights they have to share and distribute and reuse the things that you have. The second one will be the readme, this is like the welcome mat that just tells everyone hey you’re here. Here’s what we’re about. And then we also we have some contribution guidelines, and we will have a code of conduct as well. So fantastically we have some guest speakers who are very experienced at working on these things. And First up, we have Hao Ye, who will speak a little bit about licenses and what open licenses mean.

Hao are you ready. You are super ready I’m gonna mute, over to you.

19:34 - Hao: Alright. Hello. Ah, so Hi, I’m here to talk to you very briefly about open licenses. The slides that I’m sharing are shared with a creative commons by license, developed by open life science and then modified by me. I am not a lawyer I only play one when playing board games. Okay. So a little bit about me. I am the reproducibility librarian at the Health Science Center libraries at the University of Florida, my pronouns are he/him/his, and my Twitter handle is @Hao_and_Y, do feel free to reach out to me.

If you have questions about research reproducibility or other related topics. So the goal and talking about licensing, in the context of open life science is and open project is, we would like other people to be able to use remix and share our the work that we’re doing in our open projects. And we achieve that by making sure that we have in our open projects, explicit documentation about how other people can use and remix and share it.

And so we’re gonna go through these slides, and hopefully if there’s time, you know, have the ability to have a short discussion or answer any quick questions about this, with the goal being that you will eventually know and understand the importance and how exactly to do the task of adding an open license to your work. Okay. And so going back to kind of the intent behind all of this, the open leadership framework talks about open leaders as designing and building projects that empower others right we think about, we’re doing these projects because usually because we care about doing work that you know helps other people whether those are people in our communities or outside our communities.

And so that’s kind of where we think about one way in which you know we do that interaction is by having our work be shared in a way that other people can can use it. And so this falls in this box of the open leadership framework of building for sharing and making sure that we have explicitly in the building of our project, a way that we share the work. Okay, so some, some misconceptions that I think I want to address when talking about licensing, because it is a it is a complex topic, and it does relate to things like copyright, and academic credit, but licensing is not the same thing.

And so some brief kind of points to make really quickly. Just because you share something on the internet or GitHub or someone else share something on the internet or GitHub does not automatically allow other people to use it. If you are sharing work with a license. It does not by default give away your copyright, so you can share work with a free license and an open license like Creative Commons.

22:59 - That does not prevent you from publishing your work, or selling your work, or in other ways monetizing your work. And finally, a work that has been shared with an open license. You can use it, and other people can use it, they don’t have to cite you necessarily. Ah, so it can be legal to use the work without citing you, but in an academic setting if you are doing academic research that’s still considered a violation of academic ethics.

And that is something that you would pursue. if it’s a problem using academic means, because that can be plagiarism. Okay. So some, some kind of common elements when we talk about licenses There are of course many different ways. You can you can give other people permissions on so many different example licenses, and the kind of things that we think about in terms of including in the open license are how people can use your work, how people can modify your work and how they can share your work and redistribute either the original or the modified work to other people.

24:16 - And so, yeah, Some of these elements also include attribution. So a lot of the open licenses that are in use, generally require that if the work is being reshared by someone else that the original authors are credited. So examples of this are the Creative Commons by license, which has a this attribution clause, and almost all the other licenses that will be mentioned today. And one exception to this one important exception to this is the Creative Commons zero license, which effectively is putting something into the public domain and waiving, your copyright to to whatever it is that you are sharing using the CC0 license.

So some, some kind of So some some kind of advanced complications. Within this topic of open license. So I put these as I list these as wrinkles because they are relevant to kind of consider, but maybe. Don’t think too much about making sure you understand all the details of it. Open licenses have this distinction between what we call copyleft and non copyleft licenses, which basically have to do with whether modifications of a work, have to be shared, under the same principles.

The idea with the copyleft licenses, so something like the GNU PUBLIC LICENSE the GPL is that if someone writes a piece of software and shares it with that license, a company can’t just build off of that software, and then sell their modifications. They also have to distribute their modifications in the same license. And that way, it’s a way of ensuring that kind of, if you’re going to use something in the copyleft world that you also contribute to that world.

And this is not true for licenses that are permissive but not in the copyleft scheme. And we generally prefer those, and the kind of open licensing world and I think for, you know, open life science, we don’t necessarily want to be overly restrictive with how people can reuse our work, but that is, if that is something that is important to you. That is something to consider. The next thing is that patents are also not related to copyright, which are not are not the same thing as licensing.

So, copyright rights include the ability to copy, modify and redistribute work and patent rights include the ability to use make and sell work. And so this generally tends to come up when we are talking about software in that open source licenses for software may or may not explicitly include something that grants, patent rights. And this is a whole big can of worms. So I’ll just say if you are writing software, and you have a plan to patent, the software in any way, definitely talk to a lawyer before thinking before just slapping an open license and expecting that your patent rights will be preserved.

27:49 - Okay. That was a lot. So let’s go into the, the kind of details of how you go about applying the license. So, a license file is usually named license in all caps, and it goes in the root directory or the top most folder of your project. And you can definitely include multiple licenses, and that’s important because you might have different components of your project that you want to apply different licenses to. And that’s kind of important because licenses that are best for software are not ideal for content like images or writing.

And in the reverse as well. And so there are ways that you can specify in the license section of your README or the license file, exactly which parts of your project are associated with which license.

28:48 - So again, data, and code and creative works are not the same thing. And so you might require different licenses on here’s an interesting tweet I saw earlier this week about this topic that is relevant. And so ways that you can add a license to your project in GitHub. If you are creating a new repository and GitHub, there’s a section at the bottom where you can initialize the repository. By clicking that checkbox, and then you can choose a license from among a number of built in defaults to GitHub, so that’s a way you can just start out a project with a license.

But if you already have a project on GitHub. There’s another way you can add one of these licensed templates, which is when you use the feature to add a new file. If you start typing the file name license in all caps, a button pops up, which lets you choose a license template. And that’s also really handy to have in that, again, you don’t have to go look for the full text of a license and get the file. If you’re just working in GitHub. Those are built in defaults, using the MIT license.

If you are sharing writing or documents or images, the CC-BY license or for data that you use the CC0 license, which effectively puts it into public domain. So these slides are all linked to from the notes, and that was a lot.

31:59 - I’m going to go ahead and stop screen sharing and answer questions if we have time Do we have time.

32:10 - Yo Yehudi: I think we have time for just like one or two quick questions but I know you need to hop off as well. So yeah, I think we have a question about the GitHub chooser and creative commons license from Jennifer Miller. Do they include creative comments or is it just software.

32:30 - Hao: It’s a good question. Let me test that out really quick.

32:43 - Yo Yehudi: If anyone else has any other questions there we go got more coming in.

32:48 - Hao: I think they only have CC zero. Yo Yehudi: Yeah.

32:52 - I think you could still use the Creative Commons chooser and add it in, but it might be one that you can’t use by default. I have another question here How do you have a recommendation for licenses for educational resources. Ah, Hao: yeah, I use, I use CC-BY for all of my educational resources. If you go to Zenodo, and you look up my name you will find several, several lessons, and content that I share generally CC by for all of those because they’re not they’re not, I’m not sharing code, generally.

33:32 - Yo Yehudi: Okay, I think this will need to be the last question for now folks but please do add more and we’ll add them into the document and try and follow up later. But Carla asks, Why would you choose CC0, instead of CC-BY for data, great question.

33:47 - Hao: Great question, are really challenging to answer all there are, I think there’s a legal gray area that has to do with whether you can actually copyright data. Certainly you cannot copyright facts, like the sun is a star, you cannot copyright that. And there’s a question of whether data is something that can be copyrighted, and that there is artistic expression in the collection and nurturing of data, but not necessarily in maybe the data itself.

So that’s just a can of weird legal stuff that I don’t know how to deal with. But CC0 is just kind of makes sure that the data can be used again, it doesn’t cover academic credit, so if you want to have academic credit for the data. We recommend that you deposit it in a data repository where you have a DOI that can be cited academically and not to try and pursue attribution in illegal means through, for example the CC-BY license which requires legally that anyone using it and reshoring it provides attribution Yo Yehudi: Beautiful.

35:07 - Thank you so much Hao I think, in the name of time although I suspect this could be a long q&a session in the name of time we should probably move on to the very next thing. Emmy, I think you’re the host for this section I’m going to drop off in a minute so.

35:22 - Emmy Tsang: Yep, thanks Yo. Yeah, so on to our second document-README. we’re very happy to have Carlos from the Netherlands eScience Center with us today. Carlos whenever you’re ready.

35:39 - Carlos: Hello. Okay. So, Emmy. I think you’re quite close to Emmy Tsang: mmYes, I am Amsterdam Science Park right.

35:57 - Carlos: I think, if you go to. So there’s a cycle path that goes from Amsterdam Science Park and. And then you can cycle along the canal for a bit, and then you go through Weesp, which is quite nice. And then you can cycle all the way to Bussum. So we did this one last summer, and it is quite actually quite nice because person is like completely surrounded it has like a moat around the whole city. So it’s very nice, it’s cycle path is quite short I think for you it would be maybe under an hour you should be there.

Okay, now I’m hoping that everybody else is who is thinking, who is this guy. What is he talking about why is he ignoring the rest of us, and what is he, what, what’s the point of this talk, that was exactly my point is, I’m doing this in a presentation usually you start by saying, Hi, my name is Carlos Martinez I work for the eScience Center and I’m going to be talking to you about README files. That’s the part of the presentation where you usually introduce yourself and tell people this is what I’m going to be telling you in the next five to 10 minutes.

So I deliberately asked Emmy to help me to do, completely the opposite to show a bad example of how you should not make a presentation. Because it’s the same thing that you have with a readme file. So I’m going to be telling you about README files.

37:29 - How README files are useful to communicate about your project.

37:34 - So README files are really like a, the welcome the welcoming part of your project. They’re the presentation card for your project where you would say okay this is my introduction card.

37:49 - This is my project. This is what my project is about. This is what my project does, and it should provide you all of the initial information for your project for what are you going to eat what is project is about what the, I don’t know if it’s a software project. What type of software, it is which dependencies it uses on which language is written, what’s the, what problem it solves. So, these are all the things that you want to have in your README file for introducing your project.

When somebody finds your project on GitHub. And they read your README file that’s the first thing that they see that’s the first impression that they have about your project. And that’s a basically that’s the moment where people meet your project. And that’s either they like your project or they don’t like your project. Either they will use your software or they will not use your software, but a readme is very important because it’s that first moment that is that introduction to your project these days your projects landing page is your projects presentation card.

So that’s why the readmes are very important. Usually readmes in GitHub, you on software projects you just have a file, which is a plain text file called README with all capitals, or README mark you can use markdown on readmes as well. And that’s the first page that you will have on your GitHub repository. So, in your README, what are the important things that you should have in your README. If you should say what was your project is doing, for whom, and why.

So this is really the giving the context to your project. You should tell a what makes your project special by the you build this new software library that does the same that other libraries what sets your, your specific software or your specific tool or your specific project apart from other projects that are already out there, and how to, how to get started so if this is a software project, how would you install this tool or how would you use it, or if it’s a.

I don’t know if it’s a book like the Turing way, how, how you would get started contributing to this project or how would you get started using this project. And usually it’s also also always a good idea to point to useful resources about your project. So again, if it’s a software project, and it’s already distributed through package manager, where can you find the links to you to the package manager that manages your software, or if this is the, the readme for a project, and you have a website, maybe you also want to point to your website.

So, where are all the other resources that are useful and relevant for your project.

41:01 - Okay. So, again, in terms of bad examples good examples. If this was my software project, and this is my README file. This is a terrible README file. So it has the name of my project and it tells you how, how do I run my code, and how to cite my paper, but it doesn’t tell you what my software does. Why would you use it in which context, would you use it. What problem does it solve. How is it read then where is the documentation so there is absolutely no information about it.

Maybe it’s useful for me to remember how to run my code. But even for myself in three weeks time I will forget what my project was about and I would remember what’s the tool that I was using for days now I don’t know I can’t remember anymore. So I think this is the best example I could think of, of a terrible README file. And maybe the, the only thing that could be worse is to not have a readme file at all. Now, a good example. This is the readme file from the Turing way.

These tells you what is Turing way. It tells you that these are lightly opinionated guide, and it tells you that it’s aimed for researchers, and I think, yes, it also tells you where can you find the, the guide and in the readable format and not in the readme file format. So you can go to Turingway. netlify. com, so it’s telling you what it does.

42:44 - Who is it, aim for points to useful resources. And one thing that they love is that it even points you to README file in different languages so that’s a really nice example of a readme file. So, yeah, so that those are the main things that I think you should be thinking, thinking about when you write your README file. So, reiterating what they already said, is the welcome message to your website, you should share all the important information about your project.

What’s your project and mission, vision, what you want to do with this project. And it’s also a good place where you can link to relevant information for example licenses code of conduct, which as we just heard from how it’s important to state your license for software projects and other types of projects. Another thing that I think it’s important to consider is where your software is going to where your README is going to be used. So, if you write your README on GitHub.

And maybe this is a little bit I’m switching to a very software specific example. But if you’re if you’re writing a software tool and your software is on GitHub. Your users will look at your README on GitHub. But they will also be able to see your README in other places because once you connect your GitHub account with other places your README gets like harvested by Docker hub or by Pypi. And your README ends up in other places as well, and maybe it also your, if you generate that website automatically from your GitHub repo, your readme ends up there as well so it’s always useful to think how is your, how are your readers going to read the readme so try to always consider who’s going to read your README file and in which context, they’re going to read it.

Yeah, so README files context. Now, what are my top tips for readmes? I think this is an exercise I believe that we want to do later. But basically I think that my take home message and README files, is that you should always try to be clear, and try to always think of your reader always think, who’s going to read it. What information do they need, what will they learn from this README file. And what do I want them to learn by reading my README file so what is information that they want to convey to them.

So I think that’s all I wanted to say about readmes and trying to keep it, keep it short. And I don’t know if there’s any questions.

46:07 - Emmy Tsang: Thank you very much Carlos and thanks for the wonderful introduction that got me completely confused as well.

46:14 - Folks, if you have questions, please put them in the chat I think we can do maybe one or two in the interest of time, or on the chat is also completely okay and appreciated. I’m just scanning the chat now. There is one from Muhammet he’s building a tool that outputs in a report in HTML file can, can we embed a sample report HTML report dot html in the readme.

46:51 - Carlos: Can we embed. Yes. So I think if you’re using GitHub.

46:57 - You probably can link to an existing report on. Yeah, I think that would be the the, I would do it that way if you have a readme in your GitHub repo, and you already have a report I would probably link to it. Yeah, rather than embed it into README.

47:24 - Emmy Tsang: Thank you. Um, and another one. What can we put at the landing page of our website mission, vision, README? So, everything would you recommend putting all the things like mission, vision, you know that about the readme or.

47:48 - Carlos: So I would say, this is useful for your reader. So I.

47:58 - Okay, so if you have like a long mission statement long vision statement for your project. Maybe, either because you can end up with a readme that is extremely long and then it becomes unreadable and you you hit this wall of text and you don’t want to read it. But maybe if it’s just like a one sentence, then by all means, put it in your README but if you have like a rather long mentioned patient statement documents I would maybe put them in a separate place, and just point to them from my README file for people who are interested to reading those.

48:37 - Emmy Tsang: Okay. Perfect, thank you so much Carlos. Folks if you have any other questions regarding the please feel free to put them on Slack, after the session as well. Happy to brainstorm together. On the note of long vision statements. We’ve given you sort of a pre call exercise I believe that you may have time to go through but basically there’s this cool tool called upgoer5. And you can try to use it now if you haven’t had the chance before to see if you can use it to modify your mission statement.

So all you have to do is to go to the upgoer5 website.

49:22 - Let me put the link in the chat as well. Copy and paste your vision statement in there, and then see what happens.

49:36 - Unknown: And Emmy Tsang: I will, well, we’ll ask you to do that in breakout rooms as well. So, again, you’ll be split into groups of three, and you’ll have seven minutes to try this exercise out and share with each other, what you think again you’re in written and spoken room so just be aware, it’s in rooms please use the Zoom chat on the agenda to put down your thoughts, hope that’s clear and welcoming other ones now.

50:18 - Please do share your thoughts on the agenda. I’m curious to see how you’ll find it I don’t think we’ll have time to go through the comments in detail so we can all put our comments down and go back through the meeting notes.

50:37 - All right. I think all the rooms have been close so welcome back.

50:43 - Yeah, as I said, I hope you’ve found that interesting useful insightful surprising, please do share some thoughts or an upgoer5 modified mission statements in the agenda but meanwhilel, we have a very important topic to get to. So, I’ll hand it over to Malvika to talk about contributing guidelines and Code of Conducts.

51:06 - Malvika Sharan: thanks Emmy. I’m just going to acknowledge that this is very difficult. It has been always difficult for me to do the Hemingway and Upgoer5 or to simplify my language, but honestly, if you go back to any open source project who are super successful and if you try to read their vision and mission statement. They are very very simple and I think we want to achieve the simplicity, it doesn’t mean you need to take away the essence that you have in your vision statement if you feel that some words need to be there.

This is just a suggestion, it’s not a law, nobody’s going to sue you if you don’t simplify it, so do as much as you’re comfortable to do with that, I’m going to share my screen and I’m going to talk to you about code of conduct, and contribution guidelines. If you, if you come to open source Open Science space there are three documents that are essential to add to any project, when we heard earlier is about license, choose the license. Add README, so you’re choosing a license so people know how to use your material you write README so people know what it is about and if it’s useful for me.

And the last one is contribution guideline and code of conduct, so people can find your project and know how to use it, people can find your project and know what it is about. But the ultimate aim of any open source project is that allowing people to build upon it. The innovation doesn’t happen if there was nothing before us. This is where the contribution guidelines is very important so people know that you’re allowing them to use it. But in a weird way.

What we will do in my talk, I’ll try to keep it concise, but also in a way that you understand the importance of involving people.

52:53 - So we will consider how to create a positive culture for contribution and collaboration and open projects, give you a practical example of how a contributing. md file looks like, but it doesn’t need to be called contributing. md if you’re not using GitHub, it could be just contribution guideline and choosing a code of conduct, and please keep an eye on choosing, we are building on lots of open source projects so we don’t need to build everything from scratch, there’s a lot of material references out there, big one that matches most your values.

So yeah, just so you know someone asked me if the cat, cat picture is used, I think it has become our mascot and that’s why if you go to our Slack channel in random we’re just literally randomly talking about cats. So, I’m Malvika Sharan, I am the community manager of the Turing Way, which is the daytime job beside open life science. That’s not my Twitter but I left it there because a lot of ideas that I’m going to talk about comes from Lilly Winfree, and I totally, totally recommend you to follow her @lilscientista.

You can follow me as well but I’m always talking on slack so I don’t think you need more noise from me. So what is a project culture. When we want to build a project culture we need to think about if we want to build a community. Is this a project that I’m creating just for myself or do I want people to come in and hang out with me. If I want people to hang out with me, how do I want this community to look like, how would we, how would my members, be, are they gonna bring the same idea as me, or are they gonna be diverse, that they bring different perspective, they challenge me in building my project, so I can achieve better than I can do alone.

These people are also who helped you build and guide the culture, right but as a project leader, it’s your responsibility to set the tone for how your community should look like. Therefore, you need to make conscious decisions when you’re writing a readme page, or when you’re selecting the license. And when you’re creating contribution pathways for others. When you’re creating these culture you need to understand what your personal values that you’re bringing in project are, hence it becomes a project value.

And how should people behave setting expectation is very important when someone enters a new space, one of the biggest fear they encounter is not knowing anything, they don’t know what to expect they don’t know how to behave they don’t know what kind of behaviors are accepted.

55:29 - Therefore it’s important for you to let them know that this is what this project stands for. And this is how you can contribute. And there are a lot of unwritten rules which you want to get out of your brain and write it in a document or someone else can actually read it because no one can read your brain yet.

55:48 - A project culture involves more than just setting a GitHub repository or telling people by email that hey come and join me, there is a lot more to collaboration than that. It’s more than just a common goal or having different teams working on different parts or exchanging knowledge, but also understand what actually creates those kind of values. For example, if you have to be intentional about the fact if you want a diverse team, and therefore make an attempt to create a diverse team yourself.

56:18 - Things won’t happen naturally you need to invest into it. If you want to create an inclusive workspace, you need to add a code of conduct, you need to make sure that people are treating each other kindly therefore, they want to be around each other. And also when you open a conversation for discussion, say that this is open for discussion and say that you’re inviting them to be part of it. So it’s a language it’s set of norm people’s expectation the tools that you use and how decisions are being made.

It’s a project identity. So how to build your culture. Documents again, clear contribution guidelines and the code of conduct, that is enforced.

57:01 - Coming back to what is community. Community. In an ideal world, is a set of different people who come together and live in an ecosystem that is nurturing for them. They don’t have to be same opinion, they don’t have to be same background, they don’t have to be same expertise. People need people should be allowed to bring their skills and combine them in a way that their outcome is a lot more powerful than the sum of their parts. And then what does contribution.

Right. If we just talk about GitHub in GitHub, and again next week we’ll explore a lot more about GitHub so if you’re new to it. I will try to make sure that I don’t use jargons but in GitHub, you can go and write issues that a lot of you have created in OLS-3, you’ve created an issue and you become actually a contributor of that repository. And this is a picture from the turing way you can see Sarah here and that’s me and there are a lot of other folks in the GitHub you put it as a file which is called contributing.

md. and as I said if you’re not working on GitHub you would still create a page that that would be called contributing or contribution guideline. Why is it important. So you want to define what the structure of contributions look like provide guidelines on how to make those contribution, you ensure that there is a consistency across your community if people are working in different time zones, if they’re not talking to each other at least they have one place where they know how to find information.

And when you write all these down it actually improves the efficiency, you don’t need to always repeat yourself until everyone over and over what what all these guidelines, stand for. And it also allows you to involve new people, even if you don’t know who they are at the moment, if they are able to find your repository, they have this guideline to guide them how to contribute to your project. And who’s responsible for that.

59:00 - First of all, owners, meaning people who are leading the project. They are responsible to create it contributors, which are all members, they are responsible to follow it and consumers, like users and members. They can also decide if they want to share feedback with you. So this is a very, very good contribution guideline from the carpentries. The carpentries is another open source community that teaches people how to teach computation.

And it is a it is a wonderful page because it’s, it’s just a community page that gives you links to all the places you can find information. So if you’re lost you want to come back to this page and you know okay I wanted to look at trainers or I wanted to look at champions. So you if you have this one page which is called page of all links. That would be extremely useful for people to come back and orient yourself but these are generally optional because when the projects are quite new, you don’t really have a lot of files that you want to you want people to read.

You want to create a place for diverse community right and you would expect that everything is going fine and everyone’s super happy. But what happens if something goes goes wrong. What if things are not ideal anymore.

60:14 - You want to make sure that people have a place to feel welcome and protected. Therefore you want to give them a code of conduct. Code of Conduct is a set of rules. Sorry. Set of rule that outlines the social norms roles and responsibilities of an individual project party or organization. It’s commonly abbreviated as CoC. So generally, I would probably just randomly say CoC but that really stands for code of conduct.

60:43 - Do you really need a CoC. Yes, you do need a CoC. It invites people to your project, it sets clear expectation in your community and tells contributor, that you care about your community. Often the misconception is that CoC is a policy that is making people scared about the fact that they will be there will be consequences. But honestly CoC is setting tone for your community and making sure that people who would generally not become part of another community because they don’t really know if they’re welcome.

It allows them to look at what are the guidelines if someone harasses them, would there be any consequences or not. And they can make a choice based on your community culture if they want to become part of it. There are some examples and I’m going to just quickly show you. csv conf, which is one of the newest code of conduct that they had developed last year. It’s a conference. So they start with what this code of conduct is who does it apply on.

And they also have two things which is called enforcement and reporting. And I’ll quickly go through that part as well. So here that’s right they have code of conduct.

61:53 - Code of Conduct is not just a box checking item right so it’s not like oh I want to add all the documents that I would need to add, and therefore I need to add code of conduct without really reading it or meaning good. It’s not enough, you need to add enforcement and reporting guideline you need to make sure that people know how to report, who the report is going to, and what will be the process for reports to be followed through, and often you would want to have anonymous reporting because you don’t want to put pressure a lot on people.

So getting started, I would say that start by brainstorming core words that represent your community value, consider behavior that you want to encourage, think of the process for incidents and complaints and what are the consequences for those acting outside the norm, and understand and accept your role as project lead. So before we go. At the end you need to understand that open source has a lot of work that is always thankless people are doing a lot of work at the background.

Therefore, you need to encourage and reward good practices, you can, if you are willing to and if you have the capacity to designate a code of conduct, and safety committee do so, make sure that your code of conduct is quite visible and clear and communicate the process to contributors. Generally, as I said don’t try to create your own code of conduct, there are a lot of great examples of code of conduct that you can take and adapt for your community.

So what are your contributing guidelines and Code of Conduct tips. With that I’ll stop and I’m happy to take some questions.

63:34 - Emmy Tsang: Thank you very much Malvika. And folks if you have any questions. Well, there’s one already. Thank you. Can you share an example of a good CoC, I believe. We definitely can.

63:53 - Malvika Sharan: Yes. So, we have linked to the carpentries code of conduct I am actually one of the chairs of Code of Conduct there, and we have spent years revising that code of conduct it is the best we can do. If you can adopt that and make it even better. It’s great if you don’t want to do it you can literally take the copy and use it. There is another version of that code of conduct, from the Turing way where we have simplified some reporting and enforcement guidelines.

So, I think we can add both of those in the document for you to look at, but there are a lot simpler ones as well you can look at open life science. We use the covenant, I think. But there is another from to do groups so these are four or five that I’ll add in the document for you to look at.

64:41 - Emmy Tsang: Thank you. Yeah, folks, if you have any other recommendations or good sales things you’ve came across, you can also add them in the agenda. With links please. Jennifer, do you have experience or recommendations regarding whether or not ACC should provide anonymous report of concerns Malvika Sharan: I do have opinions, I do think that people should provide name, but you need to make sure how you’re protecting their identity, because if you are taking a lot of anonymous reporting.

There won’t be anyone accountable for wrong reporting, and that would fall into the person who’s handling the report. So make sure that you really ask for name but at the same time you say say how you are keeping their identity confidential. However, if people are not comfortable, they’re not going to contact you. Therefore, you can. You need to decide for yourself if you’re ready to handle anonymous reporting, we generally take anonymous reporting only at events, because people are right there, and the consequences as a result of reporting can be quite disaster.

I think so, but we don’t take anonymous reporting for communities when we are working online because we need to know who is it what really happened and if there’s nobody accountable for that there is really little, we can do Emmy Tsang: I think we’re one minute away from 30 minutes past, so maybe it’s good to round up for now.

66:14 - Malvika Sharan: Thank you for Yeah, I will, I will stick around after the call because generally people stay on for these kind of conversation off record so we’ll stop recording, after one or two minutes and if you want to stick around and I’m here. Emmy please go ahead and close it.

66:30 - Emmy Tsang: Okay, I’m gonna close the call, there is a list Okay, I’m going to close the call. There is a list of of assignments I believe on the agenda. I don’t know if we need assignments, I believe, Jenna, I don’t know if we need to. Yeah, to. Yeah, so, create a GitHub repository for your report if so create a GitHub repository for your report. If you are you are familiar with GitHub already if you’re not Don’t familiar with GitHub already, if you’re not, don’t worry in next worry, next week there will be a skill up call for all of us who week, there will be a skill up call for all of us who are just are just starting on GitHub, myself included, so that will be starting on GitHub, myself included.

So that will be Wednesday at 1. 30 CET pm. But the information is on the Wednesday at 130 cet pm. But the information is on the calendar calendar as usual. Please add a link to your GitHub repository as usual. Please add a link to your GitHub repository when you when you have one to your issue that you should have posted last have one to your issue that you should have posted last week, I week, I believe, and use your canvas to start writing a readme believe.

And use your canvas to start writing a readme file if file. If you can, and add a license add a code of conduct.

67:15 - you can, and added licence at code of conduct. Lots of stuff.

67:21 - Lots of stuff. So have a go at this and if you have any So have a go at this. And if you have any questions while doing questions while doing this, please do ask in Slack, or check this, please do ask in slack or check with your mentor as well with your mentors who will be able to help you with things.

67:32 - who will be able to help you with things. Thank you all for Thank you all for joining us today, very happy to see you joining us today. Very happy to see you all and I will stop the all. And I will stop the recording at this point. Have a recording at this point. Have a Good morning, evening, Good morning, evening afternoon wherever you are and see you in afternoon, wherever you are and see you in two weeks.

67:44 - two weeks. Malvika Sharan: I just want to add if we could stop recording.