From 803b24e6a88c676e1fbf3d15cbfec9fb8e1d085a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Wed, 21 Feb 2024 22:33:44 +0000
Subject: [PATCH 001/142] New translations welcome.md (Portuguese, Brazilian)
---
book/translation/por/book/website/welcome.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/translation/por/book/website/welcome.md b/book/translation/por/book/website/welcome.md
index e8d86139b58..c343f6b3d0c 100644
--- a/book/translation/por/book/website/welcome.md
+++ b/book/translation/por/book/website/welcome.md
@@ -1,7 +1,7 @@
(welcome)=
# Boas-vindas
-*Tenha boas-vindas ao guia The Turing Way para ciência de dados reprodutível, ética e colaborativa.*
+*Welcome to The Turing Way handbook to reproducible, ethical and collaborative data science.*
_The Turing Way_ é um projeto de código aberto, colaboração aberta e conduzido pela comunidade. Nós incluímos e apoiamos uma comunidade diversificada de colaboradores para tornar a ciência de dados acessível, compreensível e eficaz para todas as pessoas. Nosso objetivo é fornecer todas as informações necessárias para que pesquisadores e cientistas de dados na academia, a indústria e o sector público consigam assegurar que os projetos em que trabalham sejam fáceis de reproduzir e de reutilizar.
@@ -21,7 +21,7 @@ Please [join our Slack Workspace](https://join.slack.com/t/theturingway/shared_i
name: welcome-image
alt: O projeto The Turing Way é ilustrado como uma estrada ou caminho com lojas para diferentes habilidades em ciência de dados. As pessoas podem entrar e sair com o seu carrinho de compras e escolher o que precisam.
---
-_A Turing Way_ ilustração de projeto por Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807)
+_The Turing Way_ project illustration by Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807)
```
(welcome-community)=
@@ -44,12 +44,12 @@ O livro é escrito colaborativamente e aberto desde o início. Para tornar esse
name: theturingway-chapters
alt: O guia The Turing Way para pesquisa reprodutível e sua estrutura ilustradas como uma série de portas que representam a estrutura em capítulos e sub-capítulos
---
-Ilustração por _The Turing Way_ por Scriberia. Versão original do Zenodo. http://doi.org/10.5281/zenodo.3695300.
+Ilustração por _The Turing Way_ por Scriberia. Original version on Zenodo. http://doi.org/10.5281/zenodo.3695300.
```
Embora _The Turing Way_ receba apoio e financiamento do [The Alan Turing Institute](https://www.turing.ac.uk/), o projeto foi projetado para ser uma colaboração global. Temos contribuições de todo o Reino Unido e da Índia, México, Austrália, EUA e muitos países europeus. Os capítulos foram escritos, revistos e curados por membros de institutos de investigação e universidades, departamentos governamentais e indústria. Nosso compromisso é criar um espaço onde pessoas com diversos conhecimentos e experiências vividas possam compartilhar seu conhecimento com outras pessoas, para que possamos usar a ciência de dados para melhorar o mundo.
-Valorizamos a participação de todos os membros da nossa comunidade e queremos garantir que todos os contribuintes tenham uma experiência agradável e realizante. Assim, todos os que participam do projeto _The Turing Way_ devem mostrar respeito e cortesia para com outros membros da comunidade a todo momento. Todas as contribuições devem obedecer ao nosso [código de conduta](https://github.com/alan-turing-institute/the-turing-way/blob/main/CODE_OF_CONDUCT.md).
+We value the participation of every member of our community and want to ensure that every contributor has an enjoyable and fulfilling experience. Assim, todos os que participam do projeto _The Turing Way_ devem mostrar respeito e cortesia para com outros membros da comunidade a todo momento. Todas as contribuições devem obedecer ao nosso [código de conduta](https://github.com/alan-turing-institute/the-turing-way/blob/main/CODE_OF_CONDUCT.md).
From cabc39bf06b960d9bd7a7c899e253048456a1131 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:40 +0000
Subject: [PATCH 002/142] Update source file collaborators.md
---
book/website/afterword/collaborators.md | 73 +++++++++++++++++++++++++
1 file changed, 73 insertions(+)
create mode 100644 book/website/afterword/collaborators.md
diff --git a/book/website/afterword/collaborators.md b/book/website/afterword/collaborators.md
new file mode 100644
index 00000000000..d949900b9b5
--- /dev/null
+++ b/book/website/afterword/collaborators.md
@@ -0,0 +1,73 @@
+(collaborators)=
+# Collaborating Organisations and Projects
+
+_The Turing Way_ works in collaboration and formal partnership with many communities and organisations.
+The project also receives in-kind support through contributions from members who represent their communities, projects or organisations in The Turing way.
+These contributions may take different forms, such as sharing of practices, co-creating documentation, designing workshops and presentations, co-hosting events, creating illustrations, providing mentorship, leading or contributing to sub-projects and co-developing other resources.
+Some of these contributions also include projects that build alongside or upon The Turing Way resources or collaborate with The Turing Way team members in various capacities.
+We acknowledge each of these contributing members individually and list their profiles under “Collaborating organisations and projects”.
+
+(collaborators-delft)=
+## [Delft University of Technology - Faculty of Applied Sciences](https://www.tudelft.nl/en/faculty-of-applied-sciences)
+
+The Faculty of Applied Sciences is the largest of the Delft University of Technology and focuses on finding innovative solutions to some of the problems faced by society.
+Development of the fundamental knowledge needed to underpin technical developments that can be widely used throughout society.
+In ensuring that this knowledge can be shared effectively with the wider society, the Faculty values the sharing of data and code and has a [Research Data Management policy](https://www.tudelft.nl/en/library/research-data-management/r/policies/tu-delft-faculty-policies/) in place since 2020.
+In this effort, the contributions from the Faculty of Applied Sciences have mainly focused on the Reproducible Research Chapter of _The Turing Way_.
+
+### Representative
+- [Esther Plomp](https://the-turing-way.netlify.app/afterword/contributors-record#esther-plomp), Data Steward, Delft University of Technology, Faculty of Applied Sciences, Netherlands.
+
+(collaborators-escience)=
+## [Netherlands eScience Center](https://www.esciencecenter.nl/)
+
+The Netherlands eScience Center is the Dutch national hub for the development and application of domain overarching software and methods for the scientific community. Their main goal is to enable scientists with varying computing experiences to fully utilize the potential of the available e-infrastructure and allow them to achieve otherwise unreachable scientific breakthroughs. The Netherlands eScience Center is primarily funded by the National Research Council (NWO) and the National e-infrastructure Organization (SURF) of the Netherlands.
+
+The Netherlands eScience Center maintains [its own guide](https://guide.esciencecenter.nl/) for reproducible software development. The focus of the eScience Centre guide has a big overlap with _The Turing Way_ and therefore it makes sense to avoid duplicating efforts. The eScience centre contributes to _The Turing Way_ in the areas which are relevant to the eScience guide. The eScience guide points to _The Turing Way_ in which information would otherwise be duplicated.
+
+### Representative
+- [Carlos Martinez-Ortiz](https://the-turing-way.netlify.app/afterword/contributors-record#carlos-martinez-oritz), Community Manager - Software Sustainability, Netherlands eScience Center
+
+(collaborators-ols)=
+## [OLS (previously Open Life Science)](https://openlifesci.org/)
+
+Under the collaboration name OLS-4 for Turing, _The Turing Way_ collaborates with [OLS](https://openlifesci.org), a programme that helps individuals and stakeholders in research to become Open Science ambassadors.
+This collaboration offers training and mentoring to interested members from Turing and The Turing Way communities to join the OLS programme individually or in teams.
+They develop Open Science aspects in the projects that they either already have been working on or want to develop.
+
+OLS community members have been collaborating with *The Turing Way* since 2020.
+
+### Representative
+- [Malvika Sharan](https://the-turing-way.netlify.app/afterword/contributors-record#malvika-sharan), Co-Director, OLS
+
+(collaborators-scilifelab)=
+### [SciLifeLab Data Centre](https://www.scilifelab.se/)
+
+SciLifeLab, a national resource offering unique technologies and expertise to life scientists in fields like biomedicine, ecology, and evolution in Sweden, seamlessly integrates with our community of researchers, fostering collaborations across traditional boundaries with industry, healthcare, public research organizations, and international partners.
+The SciLifeLab Data Centre serves as a core division within SciLifeLab, tasked with overseeing IT and data management matters, catering to both SciLifeLab as a whole and the Data-Driven Life Science (DDLS) research program.
+We are committed to ensuring that research outputs such as data and software are Findable, Accessible, Interoperable, and Reusable (FAIR), adhering to open science principles and best practices, and optimizing the value of these outputs for the scientific community.
+
+### Representative
+- [Christopher Erdmann](https://the-turing-way.netlify.app/afterword/contributors-record#christopher-erdmann), Head of Open Science, SciLifeLab Data Centre
+
+(collaborators-eds)=
+## [Environmental Data Science Book](https://edsbook.org/welcome.html)
+
+Environmental Data Science book or EDS book is a living, open and community-driven online resource to showcase and support the publication of data, research and open-source tools for collaborative, reproducible and transparent Environmental Data Science.
+
+### Representative
+- [Alejandro Coca-Castro](https://the-turing-way.netlify.app/afterword/contributors-record#alejandro-coca), Research Fellow, Environment and Sustainability Grand Challenge Research Programme, The Alan Turing Institute
+
+(collaborators-faircookbook)=
+## [FAIR Cookbook](https://fairplus.github.io/the-fair-cookbook/content/home.html)
+
+FAIR Cookbook is an online resource that helps researchers and data managers professionals make their data Findable, Accessible, Interoperable and Reusable (FAIR).
+FAIRPlus Cookbook builds on _The Turing Way_ project and community models and provides chapters as "recipes" according to the FAIR elements, audience type, reading time, and level of difficulty.
+
+_The Turing Way_ team members and [project's editorial board members](https://fairplus.github.io/the-fair-cookbook/content/recipes/boilerplate/people.html), Susanna-Assunta Sansone and Philippe Rocca-Serra, collaborate to ensure interoperability between the two resources and exchange experiences as open source project developers.
+FAIR Cookbook [features relevant chapters from _The Turing Way_](https://fairplus.github.io/the-fair-cookbook/search.html?q=turing+way).
+Similarly, _The Turing Way_ features the project and provides an impact story titled [From FAIR Co-Author to FAIR Doer](https://the-turing-way.netlify.app/reproducible-research/rdm/rdm-stories.html) by Susanna-Assunta Sansone (a co-lead of the FAIR Cookbook project).
+You can find more details and background in the chapter [Leveraging the Turing Way Book](https://fairplus.github.io/the-fair-cookbook/content/recipes/introduction/the-turing-way.html?highlight=turing).
+
+### Representative
+- [Susanna-Assunta Sansone](https://the-turing-way.netlify.app/afterword/contributors-record#susanna-assunta-sansone), University of Oxford, Academic Lead for Research Practice; Professor of Data Readiness
From 7c424a9800dc42d177ccd4166f69ccc8d6d7ac59 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:41 +0000
Subject: [PATCH 003/142] Update source file contributors-record.md
---
book/website/afterword/contributors-record.md | 324 ++++++------------
1 file changed, 109 insertions(+), 215 deletions(-)
diff --git a/book/website/afterword/contributors-record.md b/book/website/afterword/contributors-record.md
index d57cf625510..1b90943ea51 100644
--- a/book/website/afterword/contributors-record.md
+++ b/book/website/afterword/contributors-record.md
@@ -61,36 +61,39 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Andrian Nobella
🌍 |
+ 
Andy Zimolzak
🐛 |
AngelikaKerlin
🐛 |
Angelo Varlotta
🌍 |
Aniketh Varma
🐛 |
AnkitaGarg95
🖋 |
Ann-Marie Mallon
🤔 |
- 
Anna Hadjitofi
🖋 🌍 ✅ |
+
Anna Hadjitofi
🖋 🌍 ✅ |
Anna Krystalli
💬 💡 👀 🤔 ✅ |
Anna Zanchetta
🌍 |
Annabel Elizabeth Whipp
🤔 |
Anne Fouilloux
🤔 🖋 |
Anne Lee Steele
👀 🐛 📋 |
Aras Selvi
🖋 |
- 
Arduin
🤔 🖋 |
- 
Arielle-Bennett
🤔 👀 🖋 |
+
Arduin
🤔 🖋 |
+
Arielle-Bennett
🤔 👀 🖋 🐛 |
Arron Lacey
👀 |
Aryan nath
🐛 |
Asma Kacem
🐛 |
Augustinas Sukys
🤔 |
- 
Barbara Vreede
🖋 |
- 
Batool
🤔 🖋 🌍 🚇 👀 🚧 📖 |
+
Barbara Vreede
🖋 |
+
Batool
🤔 🖋 🌍 🚇 👀 🚧 📖 |
Becki Green
🤔 🖋 |
Becky Arnold
💬 💻 📖 🤔 👀 |
Benjamin Mummery
🤔 🖋 |
Beth Montague-Hellen
📖 |
+
+
Bouwe Andela
🖋 👀 |
Brandon Lee
🐛 |
Brian O'Neil
🐛 |
@@ -100,15 +103,19 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Bruno Camino
🖋 |
Callum Mole
🤔 🚇 🚧 |
Cameron Trotter
🤔 |
+
+
Camila Rangel Smith
📖 🌍 🚧 |
Cari Hyde-Vaamonde
🤔 🖋 🐛 |
Carlos Martinez
🐛 👀 🖋 |
-
-
Carlos Vladimiro González Zelaya
🤔 |
CarlosMFerr
🖋 |
- 
Cassandra Gould van Praag
🤔 📖 👀 |
+
Cassandra Gould van Praag
🤔 📖 👀 📋 |
+ 
CeilidhWelsh
🖋 |
+
+
Cem Ulus
🌍 |
+ 
Cghlewis
🐛 |
Chad Gilbert
🐛 |
Chandler Klein
🐛 |
Chanuki Illushka Seresinhe
📖 |
@@ -116,6 +123,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Charlotte Watson
🤔 |
Chris Hartgerink
📋 |
+
+
Chris Holdgraf
💬 🤔 |
Chris Markiewicz
🤔 |
Chris Tomlinson
🤔 |
@@ -125,6 +134,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Clare Liggins
📖 |
ClauFischer
👀 |
+
+
ClaudiaCAU
🐛 |
Colin Sauze
🤔 🖋 |
Collin Schwantes
🐛 |
@@ -134,6 +145,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
DaisyParry
🖋 |
Dan Brady
🐛 |
+
+
Dan Hobley
📖 |
Dan Kerchner
🐛 |
Danbee Kim
📖 |
@@ -143,14 +156,20 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Daniel Nüst
🖋 |
Danny Garside
🐛 🖋 👀 |
+
+
Danping
🐛 |
David Foster
👀 🐛 |
David Gregg
🤔 🖋 |
+ 
David Llewellyn-Jones
🐛 |
+>>>>>>> upstream/main
David Stansby
🖋 |
DerienFe
🤔 |
Diego Alonso Alvarez
🤔 👀 |
+
+
Dimitra Blana
👀 🖋 |
Dinesh kumar
🐛 |
Dorien Huijser
🖋 |
@@ -160,11 +179,14 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Eirini Malliaraki
📖 |
+
+
Eirini Zormpa
🐛 👀 🤔 📋 |
Elisa Rauseo
🖋 |
Elisa-on-GitHub
🐛 🤔 🖋 |
Elizabeth DuPre
🚇 💬 👀 |
Em K
🖋 🐛 📝 👀 📢 |
+ 
Emmanuel G. REYNAUD
🤔 |
Enrico Glerean
🐛 |
@@ -196,11 +218,14 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Gianni Scolaro
🐛 |
+ 
Gigi Kenneth
🖋 |
Giulia Crocioni
🌍 👀 |
Goodnews Sandy
🐛 🖋 👀 |
Graham Lee
🐛 👀 |
Greg Caporaso
🐛 |
Greg Kiar
📖 👀 |
+
+
Guillaume Flandin
🖋 |
@@ -208,8 +233,10 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Hao Ye
👀 |
Heidi Seibold
🤔 🖋 |
Hieu Hoang
🤔 |
- 
Iain
👀 |
+
Iain
👀 💻 🚇 |
Ian Hinder
📖 |
+
+
Ikko Ashimine
🐛 |
@@ -219,6 +246,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
JKasmire
🐛 |
Jack Breen
🤔 🖋 |
Jade Pickering
📖 🐛 |
+
+
JadeHotchkiss
🐛 |
@@ -227,35 +256,41 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
James Robinson
🤔 💻 |
James Thomas
🐛 |
Jamie J Quinn
🖋 |
- 
Jannetta Steyn
🐛 |
- 
Jason Gates
📖 👀 |
+
Jannetta Steyn
🐛 |
+
Jason Gates
📖 👀 |
Javier Moldon
📖 |
Jay Dev Jha
🐛 |
Jennifer Ding
🐛 🌍 👀 |
Jeremy Crampton
🐛 |
+
+
Jeremy Leipzig
🐛 |
+ 
Jerry de Vos
🖋 |
Jessica
🖋 |
Jessy Provencher
🌍 |
-
-
Jez Cope
📖 |
Jill Wang
🐛 |
Jim Circadian
🖋 🤔 |
- 
Jim Madge
🖋 📖 👀 |
+
+
+
Jim Madge
🖋 📖 👀 💻 🚇 🐛 |
Joanna Leng
🖋 🤔 |
Joe Early
🤔 |
Joe Fennell
📖 |
-
-
Johanna Bayer
👀 🖋 |
Jose Urra
🤔 |
Joshua Teves
🤔 |
+
+
José María Fernández
👀 |
Julia Guiomar Niso Galán
🌍 👀 |
Julien Colomb
🖋 👀 |
K-C-Martin
👀 |
+ 
Kalle Westerling
🖋 👀 🐛 |
+ 
KarolineLeiberg
🤔 |
+ 
Katherine Dixey
🤔 |
KarolineLeiberg
🤔 |
@@ -294,7 +329,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Luna
🌍 |
- 
Lupe CaMay
👀 |
+ 
Lydia France
💻 🚇 |
MLeston2022
🤔 🖋 |
Mahwish M
🖋 🤔 |
Malvika Sharan
📖 📋 🤔 📆 👀 📢 🚧 📹 |
@@ -307,247 +342,256 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Mariana V.
🐛 🖋 |
Mariona
🖋 |
Mark Woodbridge
🤔 🖋 |
+ 
Markus Hauru
👀 |
Markus Löning
👀 🖋 |
Marta-MM
🐛 🖋 👀 |
- 
Martin Jean
🐛 |
+
Martin Jean
🐛 |
Martin O'Reilly
💬 🔧 🤔 |
Martina G. Vilas
🚇 ⚠️ 📢 📹 ✅ |
Mateus Harrington
🐛 |
Mateusz Kuzak
🐛 📋 🤔 👀 🖋 |
Matthew Evans
🐛 |
Max Joseph
👀 |
- 
Maximiliano Osorio
🖋 |
+
Maximiliano Osorio
🖋 |
+ 
Maya Anderson-González
🖋 |
Mayya Sundukova
📋 |
Melissa Black
👀 🖋 |
Michael Grayling
📖 |
Miguel Rivera
🐛 |
Mike Nolan
🤔 |
- 
Muhammad Radifar
👀 |
- 
Mukilan
🤔 |
+ 
Moritz Maxeiner
👀 |
+
Muhammad Radifar
👀 |
+
Mukilan
🤔 |
Mustafa Anil Tuncel
🐛 |
Nadia Soliman
📖 |
Naomi Penfold
👀 🤔 |
Natacha Chenevoy
🤔 |
+
+
Natalie Thurlby
💻 ⚠️ |
Nathan Begbie
🐛 🤔 |
Neha Moopen
👀 🖋 |
-
-
Neil Chue Hong
🤔 |
Nick Barlow
🐛 🖋 |
Nico
🤔 |
Nicolás Alessandroni
🤔 |
+
+
Nina
👀 |
Nomi Harris
👀 |
NotActuallyACat
🤔 |
-
-
Obi Thompson Sargoni
🤔 |
Oleg Lavrovsky
🖋 |
Oliver Clark
📖 |
Oliver Forrest
📖 🤔 🖋 👀 |
+
+
Oliver Hamelijnck
🤔 |
Oliver Strickson
💬 📖 ✅ |
Oscar Corcho
🖋 👀 |
-
-
Oscar Giles
📖 |
Pablo Rodríguez-Sánchez
🖋 |
Patricia Herterich
💬 📖 👀 🤔 🖋 📋 |
Patrick Bos
👀 |
+
+
Patrick Mineault
🐛 |
Paul Dominick Baniqued
🤔 |
Paul Owoicho
🤔 👀 🐛 📖 |
-
-
Paul Watson
🤔 |
Paula Andrea Martinez
🤔 👀 |
Pedro Pinto da Silva
🤔 |
PeterC-ATI
🤔 |
+
+
Philip Darke
🤔 |
Philip Durbin
🖋 |
Phillip Crout
🐛 |
-
-
Phome95
🤔 🖋 |
Pierre Grimaud
🐛 |
Pooja Gadige
📖 👀 |
Pradeep Eranti
🐛 |
+
+
Pranav Mahajan
🖋 |
Priyanshu Agarwal
🐛 |
Przemek Dolata
🌍 |
-
-
Rabea Müller
🐛 |
Rachael Ainsworth
📖 📋 🤔 💬 👀 📢 |
Rachael Stickland
🖋 🤔 👀 |
Radka Jersakova
🐛 🖋 |
+
+
Radovan Bast
👀 |
Rafaela Queiroz
🌍 |
Rahul Thakare
🌍 |
-
-
Raniere Silva
🖋 🐛 |
Raul Palma
🤔 🖋 |
Reina Camacho Toro
🌍 |
Reinder Radersma
🐛 |
+
+
Remi Gau
🐛 🖋 |
Reshama Shaikh
🐛 🖋 |
+ 
Richard Dushime
🖋 |
Richard Gilham
📖 🤔 |
+ 
Richard James Acton
🤔 🖋 👀 |
+ 
Richard Plant
🖋 |
+ 
Richie
🤔 🖋 🚇 |
-
Richard James Acton
🤔 🖋 |
-
Richard Plant
🖋 |
-
Richie
🤔 🖋 |
Risa Ueno
🤔 |
Robert Precious
️️️️♿️ |
Robin Long
📖 |
Rohit Midha
📖 |
-
-
Romero Silva
🌍 |
Rose Sisk
🤔 |
Rosie Higman
💬 📋 👀 🤔 |
+
+
Rosti Readioff
📖 |
SYU-NING
🤔 |
+ 
Sacha Hodencq
🖋 |
+ 
Sadie L. Bartholomew
🖋 👀 |
Samuel Guay
🌍 |
Samuel Nastase
🐛 |
+ 
Sander
🐛 |
-
Sander
🐛 |
Sangram K Sahu
🤔 |
Sara King
🐛 |
Sara Villa
🖋 |
Sarah Gibson
💬 💻 📖 🔧 👀 📢 🤔 ✅ 📹 |
Sarah Jones
🖋 |
Sarah Miller
🤔 🖋 |
+ 
Sarah Stewart
📖 🤔 |
-
Sarah Stewart
📖 🤔 |
Sarah Young
🐛 |
SarahAlidoost
🖋 |
Saranjeet Kaur
🤔 🖋 |
Sean Hughes
👀 |
Sebastian Spier
🐛 |
Sedar Olmez
🤔 |
+ 
Sergi
🌍 👀 |
-
Sergi
🌍 👀 |
Shankho Boron Ghosh
🐛 |
Sharana Shivanand
🐛 |
Shashank
🐛 |
Shern Tee
🖋 |
Shreya Dimri
👀 🖋 |
Sian Bladon
🤔 |
+ 
SianC
🐛 |
-
SianC
🐛 |
Siba Smarak Panigrahi
🐛 |
Simon Christ
🐛 🤔 🖋 |
Simon Duerr
🐛 👀 |
Siphiwe
🐛 👀 🖋 |
Solon
🤔 |
Sophia Batchelor
👀 🤔 🚧 📢 ⚠️ 📋 🐛 |
+ 
Sophie J Mann
🤔 🖋 |
-
Sophie J Mann
🤔 🖋 |
Sparkler
🌍 |
Srishti Nema
🐛 🖋 |
Stefan Janssen
🌍 |
Stefan Radic Webster
🐛 |
Stefan Verhoeven
🖋 |
Stephan Druskat
📖 🖋 🤔 |
+ 
Stephen Eglen
👀 |
-
Stephen Eglen
👀 |
Sumera Priyadarsini
🐛 |
- 
Susana Roman Garcia
💬 |
+
Susana Roman Garcia
💬 🖋 |
Susanna-Assunta Sansone
📖 |
Sven van der Burg
🖋 |
Tania Allard
🤔 💬 |
Tanya Yankelevich
🖋 |
+ 
Tarek Allam
🚇 📖 |
-
Tarek Allam
🚇 📖 |
Tess Gough
🤔 |
Thomas Sandmann
🌍 |
Thya van den Berg
📋 |
Tim Head
💬 🤔 |
Tim Myers
🐛 |
Tim Powell
🤔 🖋 |
+ 
Tony Yang
📖 🌍 🚇 |
-
Tony Yang
📖 🌍 🚇 |
Trish
🤔 🖋 |
TueloNtlotlang
🐛 |
Tushar Rohilla
🐛 🖋 |
Varachkina
🖋 🐛 |
VatsalNagelia
🖋 |
Veronika Cheplygina
🤔 🖋 |
+ 
Vicky Smith
🖋 |
-
Vicky Smith
🖋 |
Victoria
🤔 |
Victoria Dominguez del Angel
🐛 |
WNekesa
🖋 |
Warrick Ball
🤔 🖋 |
Wiebke Toussaint
🐛 |
Will Hulme
📖 |
+ 
Wolmar Nyberg Åkerström
👀 |
-
Wolmar Nyberg Åkerström
👀 |
Xiaoqing Chen
🤔 |
Yanina Bellini Saibene
🖋 🌍 👀 🤔 |
Yash Varshney
🐛 |
Yini
🌍 |
Yo Yehudi
📖 👀 🤔 |
Yu-Fang Yang
🐛 |
+ 
Zeena-Shawa
🖋 |
-
Zeena-Shawa
🖋 |
ZoeIngr
🖋 |
abrown41
🤔 🖋 |
acork25
🤔 |
acrall
🐛 |
akira-endo
🤔 |
alessandroragano
🤔 |
+ 
alihumayun
🐛 👀 |
-
alihumayun
🐛 👀 |
andreabecsek
🤔 |
andrealuppi
🤔 |
annarae13
🖋 |
ashatitus
👀 🖋 |
beccawilson
️️️️♿️ |
benkrikler
🤔 🖋 |
+ 
brynnelliott
🐛 |
-
brynnelliott
🐛 |
caroldutra3
🤔 🐛 |
ceciledebezenac
🤔 |
claudia-belardi
👀 |
daniguariso
🤔 |
dumei00
🤔 🖋 |
ghuangcazza
🤔 🖋 |
+ 
giuliaok
🤔 |
-
giuliaok
🤔 |
glumand
🌍 |
grczh
🖋 |
griff-rees
🐛 |
harisood
🐛 🖋 |
hlnicholls
🖋 👀 |
iramosp
🐛 |
+ 
irenekp
🖋 |
-
irenekp
🖋 |
jonnyhorsley
🤔 |
+ 
juli arancio
🖋 |
keneuoe
🤔 🖋 |
kgrieman
🤔 |
kkaryono
🤔 🖋 |
@@ -559,7 +603,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
lottycoupat
🐛 🖋 |
lukehare
🚇 🚧 |
mahmoud-elsherif
🖋 |
- 
mcnanton
🐛 🖋 |
+
mcnanton
🐛 🖋 🤔 🌍 |
meliimming
🐛 |
mengyucui123
🤔 |
@@ -570,36 +614,37 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
mjcasy
🤔 🖋 |
mkhslaa
🖋 |
msanter01
🌍 📢 |
- 
oxpeter
🐛 |
+ 
myyong
💻 🚇 |
+
oxpeter
🐛 |
pascalflohr
🐛 |
peterrhysstrong
🤔 |
rabbits99
🌍 |
rachelzwalker
🤔 🖋 |
raptorchief
🐛 |
- 
rickdkk
🖋 |
- 
robbykha
🖋 |
+
rickdkk
🖋 |
+
robbykha
🖋 |
russellmartin321
🐛 |
sallyob123
🤔 |
sethsh7
🤔 |
sgichuki
🖋 🐛 |
sliaqat3
👀 |
- 
smasarone
🤔 |
- 
snehashish-ghosh98
🐛 |
+
smasarone
🤔 |
+
snehashish-ghosh98
🐛 |
srtmohan
🤔 🖋 |
swalkoAI
🤔 |
takuover
🤔 |
timothy22000
🌍 🖋 🚇 |
tpronk
🐛 |
- 
tugceoruc
🤔 |
- 
vasilisstav
🤔 |
+
tugceoruc
🤔 |
+
vasilisstav
🤔 |
vcpope
📢 |
vhellon
👀 🖋 |
yaseminturkyilmaz
📝 🤔 |
@@ -614,154 +659,3 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
Contributions of any kind welcome!
-
-(contributors-record-collaborators)=
-## Collaborating Organisations and Projects
-
-*The Turing Way community receives in-kind contributions from members supported by their employers, projects or organisations for their participation.
-Such contributions are applicable when one or multiple members from a project or organisation collaborate to build and maintain resources in The Turing Way.
-These contributions also include projects that build upon The Turing Way resources or collaborate with The Turing Way team members in various capacities.
-We acknowledge each of these contributing members individually and list their profiles under “Collaborating organisations and projects”.*
-
-### [Delft University of Technology - Faculty of Applied Sciences](https://www.tudelft.nl/en/faculty-of-applied-sciences)
-
-The Faculty of Applied Sciences is the largest of Delft University of Technology and focuses on finding innovative solutions to some of the problems faced by society.
-Development of the fundamental knowledge needed to underpin technical developments that can be widely used throughout society.
-In ensuring that this knowledge can be shared efectively with the wider society, the Faculty values the sharing of data and code and has a [Research Data Management policy](https://www.tudelft.nl/en/library/research-data-management/r/policies/tu-delft-faculty-policies/) in place since 2020.
-In this effort, the contributions from the Faculty of Applied Sciences have mainly focused on the Reproducible Research Chapter of _The Turing Way_.
-
-#### Esther Plomp
-
-* Roles:
- * Project Memebr (2020-Present)
- * Book Dash Participant 2020
- * Book Dash Planning Committee 2021
- * Semi regular co-working call crasher
-* GitHub id: [EstherPlomp](https://github.com/estherplomp)
-* ORCID: [0000-0003-3625-1357](https://orcid.org/0000-0003-3625-1357)
-* Twitter: [@PhDToothFAIRy](https://twitter.com/PhDToothFAIRy/)
-* Short bio:
-> I'm a Data Steward at the Delft University of Technology, Faculty of Applied Sciences, in the Netherlands, where I support researchers with their data management and open science practices. For my PhD research, I analysed human teeth for their isotopic/chemical composition in order to say something about human mobility patterns (fields of forensics, archaeology, osteology). Next to the Turing Way I'm also involved with other teams, such as the [Open Research Calendar](https://openresearchcalendar.org/) ([follow the calendar on Twitter!](https://twitter.com/OpenResearchCal)), [IsoArcH](https://isoarch.eu/) and I was an [OLS3](https://openlifesci.org/ols-3/) mentor! I'm also interested in anything related to physical samples in research, and I'm a co-chair of the [Research Data Alliance Physical Samples Interest Group](https://www.rd-alliance.org/groups/physical-samples-and-collections-research-data-ecosystem-ig).
-
-* Personal highlights:
-> Thanks to the Turing Way I really learned how to work collaboratively using GitHub. The book dash in February 2020 was a great kick start to actually practice and directly apply these skills, which now allows me to contribute more confidently to other projects as well! I primarily contributed to the Reproducible Research Chapter, to the Research Data Management section, and to the Research Infrastructure Roles. I reviewed existing content and I'm working on adding a section on Data Management Plans and how to handle personal data. I also made a [The Turing Way poster](https://doi.org/10.5281/zenodo.4263403) that I presented during a conference. I hope to pay it forward and facilitate others in learning how to work with GitHub through The Turing Way or The Carpentries workshops. I'm very grateful to be part of this great and inclusive community!
-
-* More information:
-> I think scientific research should be accessible to anyone that would like to learn and contribute.
-> I'm hoping to bring together specialists from my research field to establish guidelines for isotopic data from human remains and guidelines for how to handle and document physical samples.
-I'm a co-chair of the Research Data Alliance group [Physical Samples and Collections in the Research Data Ecosystem IG](https://www.rd-alliance.org/groups/physical-samples-and-collections-research-data-ecosystem-ig).
-Please do get in touch if you work with physical samples and would like to get involved!
-> I'm part of the Open Research Calendar Team.
-This is a calendar that you can use to stay up to date with open research events, or add your own events to in order to increase visibility.
-Visit us at the [Open Research Calendar Website](https://openresearchcalendar.github.io/) or follow the calendar on [Twitter](https://twitter.com/OpenResearchCal)!
-
-* Quote:
-> Being a part of the organising committee for the online Book Dashes was an exciting opportunity for me to look behind the organisation scenes and to be a part of an amazing team. The BookDashes themselves are absolutely amazing, especially the discussions and the 'show and tell' sessions!
-
-### [Netherlands eScience Center](https://www.esciencecenter.nl/)
-
-The Netherlands eScience Center is the Dutch national hub for the development and application of domain overarching software and methods for the scientific community. Their main goal is to enable scientists with varying computing experience to fully utilize the potential of the available e-infrastructure and allow them to achieve otherwise unreachable scientific breakthroughs. The Netherlands eScience Center is primarily funded by the national research council (NWO) and the national e-infrastructure organization (SURF) of the Netherlands.
-
-The Netherlands eScience center maintains [its own guide](https://guide.esciencecenter.nl/) for reproducible software development. The focus of the eScience center guide has a big overlap with _The Turing Way_ and therefore it makes sense to avoid duplicating efforts. The eScience center contributes to _The Turing Way_ in the areas which are relevant for the eScience guide. The eScience guide points to _The Turing Way_ in when information would otherwise be duplicated.
-
-Details of each members with their contributions have been listed alphabetically.
-
-#### Carlos Martinez Oritz
-
-* Role:
- * Project Memebr (2020-Present)
- * Book Dash Participant 2020
- * Book Dash Planning Committee 2021
- * Community Manager for eScience Center
-* GitHub id: [c-martinez](http://github.com/c-martinez)
-* ORCID: [0000-0001-5565-7577](https://orcid.org/0000-0001-5565-7577)
-* Short bio:
-> Carlos obtained his PhD in Computer Science at the University of Exeter. Afterwards he worked on various research projects at the University of Exeter and Plymouth University. At the eScience Center, he has worked as an engineer in diverse projects in digital humanities and life sciences, developing expertise in natural language processing, linked open data and software sustainability. He is also a certified Software Carpentry instructor and is frequently involved in organising trainings.
-
-* Personal highlights:
-> We always advocate for software reuse and collaborative development of software. I love that we can do the same for software development guidelines: reuse content from the eScience guide and collaboratively develop with _The Turing Way_ community!
-
-* More information:
-> I am a big advocate of improving software quality. I am really glad that the eScience center is collaborating with _The Turing Way_ in providing guidelines and helping build better research software.
-
-#### Mateusz Kuzak
-
-* Role:
- * Project Memebr (2020-Present)
- * Book Dash Participant/Helper 2020
-* GitHub id: [mkuzak](http://github.com/mkuzak)
-* ORCID: [0000-0003-0087-6021](https://orcid.org/0000-0003-0087-6021)
-* Short bio:
->Mateusz obtained his master degree in Biotechnology with specialization Biophysics, at the Jagiellonian University, Krakow, Poland. In September 2019 Mateusz joined the Netherlands eScience Center in the role of Community Officer with the focus on communities and training around Research Software Engineering, software best practices and sustainability, and the role of software in open science and reproducible research. Since 2015, Mateusz has been involved in the Carpentries community, first as an instructor, later contributor, mentor, Executive Council member and instructor trainer. He is also leading the Dutch chapter of the Carpentries and is on the core team of nl-RSE community.
-
-* Personal highlights:
-> I have personally contributed to _The Turing Way_ by drafting chapters in the guide for Reproducible Research, reviewed other contributor's Pull Requests and mentored contributions from Netherlands eScience Center.
-
-### [FAIR Cookbook](https://fairplus.github.io/the-fair-cookbook/content/home.html)
-
-FAIR Cookbook is an online resource that helps researchers and data managers professionals make their data Findable, Accessible, Interoperable and Reusable (FAIR).
-FAIRPlus Cookbook builds on _The Turing Way_ project and community models, and provides chapters as "recipes" according to the FAIR elements, audience type, reading time, and level of difficulty.
-
-_The Turing Way_ team members and [project's editorial board members](https://fairplus.github.io/the-fair-cookbook/content/recipes/boilerplate/people.html), Susanna-Assunta Sansone and Philippe Rocca-Serra, collaborate to ensure an interoperability between the two resources and exchange experiences as open source project developers.
-FAIR Cookbook [features relevant chapters from _The Turing Way_](https://fairplus.github.io/the-fair-cookbook/search.html?q=turing+way).
-Similarly, _The Turing Way_ features the project and provides an impact story titled [From FAIR Co-Author to FAIR Doer](https://the-turing-way.netlify.app/reproducible-research/rdm/rdm-stories.html) by Susanna-Assunta Sansone (a co-lead of the FAIR Cookbook project).
-You can find more details and background in the chapter [Leveraging the Turing Way Book](https://fairplus.github.io/the-fair-cookbook/content/recipes/introduction/the-turing-way.html?highlight=turing).
-
-#### Susanna-Assunta Sansone
-
-* Role:
- * Book Dash Participant 2019
-* GitHub id: [susannasansone](http://github.com/susannasansone)
-* ORCID: [0000-0001-5306-5690](https://orcid.org/0000-0001-5306-5690)
-* Short bio:
-> Susanna-Assunta Sansone is an Associate Director and Principal Investigator at the Oxford e-Research Centre, and an Associate Professor in the Department of Engineering Science of the University of Oxford.
-> She is also a Consultant for Springer Nature, and Founding Honorary Academic Editor of the Scientific Data journal.
-
-* Personal highlights:
-> TBA
-
-* More information:
-> Susanna-Assunta Sansone's motto is "Better data for better science".
-> With her group of brilliant research software & knowledge engineers, she researches and develops methods and tools to improve data reuse; they work for data transparency, research integrity and the evolution of scholarly publishing.
-> She also conducts research-on-research, to improve how research is practiced and shared.
-> Specifically, she strives to make digital research objects, including data, Findable, Accessible, Interoperable and Reusable, FAIR, for humans and for machines.
-
-#### Philippe Rocca-Serra
-
-* Role:
- * Book Dash Participant 2020
-* GitHub id: [proccaserra](http://github.com/proccaserra)
-* ORCID: [0000-0001-9853-5668](https://orcid.org/0000-0001-9853-5668)
-* Short bio:
-> Philippe Rocca-Serra received a PhD in Molecular Biology from the University of Bordeaux, moving to the field of bioinformatics upon joining the Microarray Informatics Team at the EMBL-EBI, Cambridge. There, working at establishing ArrayExpress, he became an active member of several standardisation efforts aimed at promoting the vision for open data and open science. As part of several EU projects in toxicogenomics and nutrigenomics, he coordinated the development of the ISA project [1], which now continues at the University of Oxford e-Research Centre.
-
-* Personal highlights:
-> TBA
-
-### [Open Life Science](https://openlifesci.org/)
-
-Under the collaboration name OLS-4 for Turing, _The Turing Way_ collaborates with [Open Life Science (OLS)](https://openlifesci.org), a programme that helps individuals and stakeholders in research to become Open Science ambassadors.
-This programme is cofounded by Bérénice Batut, Malvika Sharan and Yo Yehudi.
-This collaboration offers training and mentoring to interested members from Turing and The Turing Way communities to join the OLS programme individually or in teams.
-They develop Open Science aspects in the projects that they either already have been working on or want to develop in the near future.
-
-You can see the projects that participated in the second round - [OLS-2](https://openlifesci.org/ols-2/projects-participants/) and the third round - [OLS-3](https://openlifesci.org/ols-3/projects-participants/).
-This collaboration was awarded the Turing Online Training grant to support Turing projects in the fourth round ([OLS-4](https://openlifesci.org/funders)) and share materials openly in the Turing training network.
-
-### [Remote Computational Project Resource](https://isabelbirds.github.io/Remote-Computational-Project-Resource/welcome.html)
-
-This resource was started by Isabel Birds during the COVID-19 pandemic to support students transferred from wet to remote dry lab projects at short notice.
-This project includes links to (1) general tutorials for the complete beginner, (2) tutorials for specific analyses or pipelines, (3) free online textbooks, and (4) places to ask for help.
-
-#### Isabel Birds
-
-* GitHub id: [IsabelBirds](http://github.com/IsabelBirds)
-* ORCID: [0000-0001-8173-3879](https://orcid.org/0000-0001-8173-3879)
-* Short bio:
-> Isabel is a PhD candidate at University of Leeds working on dissecting the function and molecular evolution of long non-coding RNAs Supervised by Dr Julie Aspden, Dr Mary J O’Connell and Dr David Westhead.
-> She has been interested in molecular evolution and the applications of bioinformatic techniques throughout her degree, and developed these interests while undertaking research projects in the Aspden and O’Connell labs.
-> She also has experience of scientific research from a funders perspective, gained during her year in industry and numerous summer internships with Yorkshire Cancer Research.
-
-* Personal highlights:
-> After learning about the Turing Way I was inspired to create a site aimed at a wider audience. The Turing Way tutorials helped me to set up my first Jupyter Book, helped me to create the site in a way that is open to contributions, and made sharing my work openly less scary! The Turing Way also pops up a few times in the resources listed.
-> The aim of the resource is to make starting a computational project less overwhelming by curating links to tutorials and online textbooks. Skills such as file management or asking for help effectively are also highlighted, along with entertaining things like podcasts as a reminder that research can be fun!
From 46559ad98c198fce1feaad9007fe393b18a38212 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:42 +0000
Subject: [PATCH 004/142] Update source file glossary.md
---
book/website/afterword/glossary.md | 24 ++++++++++++++++++++----
1 file changed, 20 insertions(+), 4 deletions(-)
diff --git a/book/website/afterword/glossary.md b/book/website/afterword/glossary.md
index 010eb2cfede..589d6bfb140 100644
--- a/book/website/afterword/glossary.md
+++ b/book/website/afterword/glossary.md
@@ -18,6 +18,11 @@ Add
Adversarial Learning
A process under which learning systems are exposed to negative stimuli, such as the addition of purposefully manipulated data samples, in order to obtain potentially-beneficial effects. Examples of this technique may include the addition of additional learning objectives which penalise unwanted characteristics of a learning system, for example the ability to distinguish between data records based on inappropriate demographic attributes.
+Artificial intelligence (AI)
+ The ability of synthetic computational systems to perform tasks and activities usually associated with biological, especially human, mental and intellectual capabilities.
+ Also the field of study associated with imbuing synthetic systems with these capabilities.
+ See also {term}`Machine Learning (ML)`
+
Authors
Authors in this context are the contributors to _The Turing Way_ project who have made a substantial contribution to the project such as writing a subchapter, facilitating community interactions, maintaining project’s infrastructure and supporting the participation of others through mentored-contributions. All authors are named co-authors on the book as a whole.
@@ -130,13 +135,13 @@ CRediT Taxonomy
```{glossary}
Data repository
- See repository.
+ A storage place on the internet where resources (data, software, publications or anything else) can be stored and accessed. Often data repositories provide long term preservation and persistent identifiers for the research objects stored. A data repository is the container for data and metadata, whereas a database is the structure that is used to store and manage that data.
Differential privacy
A strategy to provide quantifiable privacy guarantees when working with datasets containing personal information. The idea is that if the effect of making a single arbitrary substitution of a single record within the dataset on an aggregated query is below a specific threshold, then the result of any such query would not reveal substantial information about any individual member.
DMP
- Data management plan.
+ Data Management Plan.
DNS
Domain Name System.
@@ -229,6 +234,9 @@ Guarantor
## H
```{glossary}
+Hazard
+ Inherent qualities or characteristics of something that make it potentially harmful.
+
Head
The latest commit on the branch which is currently checked out.
@@ -321,6 +329,11 @@ Last author
```{glossary}
+Machine Learning (ML)
+ Methods which allow computational systems to extract regularities from data which permit them to perform tasks such as prediction and categorisation in a way that is at least superfially analogous to how biological systems learn.
+ A broard sub-field of {term}`Artificial Intelligence (AI)` generally distinct from Symbolic Artificial inteligence, also know as GOFAI (good old fashioned AI), which focuses on programmed systems which perform logical reasoning.
+ Machine Learning (ML) is sometimes used interchangeably with Artificial Intelligence (AI), but often employed to differentiate concrete or extant systems and algorithms from broarder and more speculative approaches to synthetic intelligent systems.
+
Machine Readable
Machine readable refers to documents, data or other digital outputs whose content can be readily processed by computers. Such documents are distinguished from machine readable data by virtue of having sufficient structure to provide the necessary context to support the business processes for which they are created. Machine readable data can be defined as data in a format that can be easily processed by a computer without human intervention while ensuring no semantic meaning is lost.
@@ -384,7 +397,7 @@ Open License
A license is a document that specifies what can and cannot be done with a work. It grants permissions and states restrictions. Broadly speaking, an open license is one that grants permission to access, re-use and redistribute a work with few or no restrictions.
Open Notebooks
- An emerging practice, documenting and sharing the experimental process of trial and error.
+ An emerging practice, documenting and sharing the experimental process of trial and error (see {ref}`Open Notebooks `).
Open Scholarship
This is a concept that extends open research further. It relates to making other aspects of scientific research open to the public such as open educational resources, having inclusive practice and citizen science.
@@ -486,7 +499,7 @@ repo2docker
A tool to build Docker images from code repositories.
Repository
- *Same as Data or Code Reprository*. A long-lived place on the internet where resources (be they data, software, publications or anything else) can be stored and accessed. This keyword is often shortened to ‘repo’.
+ A central location where resources (data, software, publications or anything else) are stored and accessed. This keyword is often shortened to ‘repo’. See Data Repository if this place is long-lived.
Reproducible
A result is reproducible when the same analysis steps performed on the same dataset consistently produces the same answer.
@@ -509,6 +522,9 @@ Research Objects
Review
Suggesting changes or asking for committing something to an already created pull request.
+Risk
+ A term that refers to the likelihood and impact of something happening. It's often used in decision-making contexts to evaluate the potential consequences of actions
+
Risk Assessment
This is used to help choose the appropriate sustainable software concepts for your project.
From d5d29b3dd2f99ed1f00bfe961d9c7fff8fa6e70d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:42 +0000
Subject: [PATCH 005/142] Update source file subprojects.md
---
book/website/afterword/subprojects.md | 101 ++++++++++++++++++++++++++
1 file changed, 101 insertions(+)
create mode 100644 book/website/afterword/subprojects.md
diff --git a/book/website/afterword/subprojects.md b/book/website/afterword/subprojects.md
new file mode 100644
index 00000000000..f8e07544cbd
--- /dev/null
+++ b/book/website/afterword/subprojects.md
@@ -0,0 +1,101 @@
+(subprojects)=
+# Working Groups, Funded Projects and Informal Initiatives
+
+This page provides access to various group-based initiatives or subprojects, listed under three themes: working groups that guide the different areas of work as a formal part of Turing's governance, funded projects that are led by members in a paid capacity and informal initiatives that are led by members through collaboration around shared interests.
+These subprojects are often time-bound and are supported by community members who take open leadership roles in response to the emergent and timely opportunities in the research and open science ecosystem.
+
+## Working Groups Led by Community Members
+
+### Translation and Localisation Working Group Leads
+
+*Project Information: [Chapter in the Community Handbook](https://the-turing-way.netlify.app/community-handbook/translation)*
+
+- [Andrea Sanchez Tapia](https://the-turing-way.netlify.app/afterword/contributors-record#andrea-sanchez-tapia)
+- [Batool Almarzouq](https://the-turing-way.netlify.app/afterword/contributors-record#batool-almarzouq)
+- [Melissa Black](https://the-turing-way.netlify.app/afterword/contributors-record#melissa-black)
+
+### Infrastructure Working Group Leads
+
+*Project Information: [GitHub issues](https://github.com/the-turing-way/the-turing-way/issues?q=is%3Aissue+is%3Aopen+label%3Ainfrastructure)*
+
+- [Brigitta Sipőcz](https://the-turing-way.netlify.app/afterword/contributors-record#brigitta-sipocz)
+- [Danny Garside](https://the-turing-way.netlify.app/afterword/contributors-record#danny-garside)
+- [Jim Madge](https://the-turing-way.netlify.app/afterword/contributors-record#jim-madge)
+- [Sarah Gibson](https://the-turing-way.netlify.app/afterword/contributors-record#sarah-gibson)
+
+### Accessibility Working Group Leads
+
+*Project Information: [GitHub issues](https://github.com/the-turing-way/the-turing-way/issues?q=is%3Aissue+is%3Aopen+accessibility+label%3Aaccessibility)*
+
+- [Liz Hare](https://the-turing-way.netlify.app/afterword/contributors-record#liz-hare)
+- [Anne Lee Steele](https://the-turing-way.netlify.app/afterword/contributors-record#anne-lee-steele)
+
+### Book Dash Planning Committee and Working Group Leads
+
+*Project Information: [Chapter in the Community Handbook](https://the-turing-way.netlify.app/community-handbook/bookdash)*
+
+- [Arielle Bennett](https://the-turing-way.netlify.app/afterword/contributors-record#arielle-bennett)
+- [Emma Karoune](https://the-turing-way.netlify.app/afterword/contributors-record#emma-karoune)
+- [Esther Plomp](https://the-turing-way.netlify.app/afterword/contributors-record#esther-plomp)
+
+## Funded Projects
+
+### Professionalising Data Science Roles - Turing's Skills Policy Award
+
+*Project Information: [GitHub repo](https://github.com/alan-turing-institute/professionalising-data-science-roles)*
+
+- [Emma Karoune](https://the-turing-way.netlify.app/afterword/contributors-record#emma-karoune)
+- [Malvika Sharan](https://the-turing-way.netlify.app/afterword/contributors-record#malvika-sharan)
+- [Alexandra Araujo Alvarez](https://the-turing-way.netlify.app/afterword/contributors-record#alexandra-araujo-alvarez)
+
+### *The Turing Way* Practitioners Hub - BridgeAI-funded Project
+
+*Project Information: [Webpage](https://www.turing.ac.uk/turing-way-practitioners-hub)*
+
+- [Malvika Sharan](https://the-turing-way.netlify.app/afterword/contributors-record#malvika-sharan)
+- [Kirstie Whitaker](https://the-turing-way.netlify.app/afterword/contributors-record#kirstie-whitaker)
+- [Alexandra Araujo Alvarez](https://the-turing-way.netlify.app/afterword/contributors-record#alexandra-araujo-alvarez)
+
+### Pathways Python Package for Curated Access to Book Chapters
+
+*Project Information: [GitHub repo in The Turing Way](https://github.com/the-turing-way/pathways) and [prototype repo in the Turing organisation](https://github.com/alan-turing-institute/bio-Turing-Way/).*
+
+**Developers**
+- May Yong, Iain Stanson, Lydia France, Malvika Sharan: funded by AI for Science and Government in 2021-2022
+- Arya A., Johanna Bayer, Malvika Sharan: 2023 Google Summer of Code (GSoC)
+
+**Maintainers**
+- [Arya A](https://the-turing-way.netlify.app/afterword/contributors-record#arya-a)
+- [Johanna Bayer](https://the-turing-way.netlify.app/afterword/contributors-record#johanna-bayer)
+- [Jim Madge](https://the-turing-way.netlify.app/afterword/contributors-record#jim-madge)
+
+### Data Science Project Management for Project Leaders
+
+*Project Information: [GitHub repo in the Turing organisation](https://github.com/alan-turing-institute/data-training-for-bioscience). Materials are hosted under The Carpentries incubator for lesson 1: [introduction to AI and Data Science](https://github.com/carpentries-incubator/managing-computational-projects) and lesson 2: [open and reproducible practices](https://github.com/carpentries-incubator/data-science-ai-senior-researchers) featuring *The Turing Way* resources.*
+
+**Developers**
+
+- Malvika Sharan, Lydia France, Federico Nanni: : funded by AI for Science and Government in 2021-2022
+- Julien Colomb (in-kind from TU Berlin) and Jo Havemamm from Access to Perspective (funded by the Turing's Health Research Programme): 2023
+
+**Maintainers**
+- [Julien Colomb](https://the-turing-way.netlify.app/afterword/contributors-record#julien-colomb)
+- [Malvika Sharan](https://the-turing-way.netlify.app/afterword/contributors-record#malvika-sharan)
+
+## Informal Initiatives
+
+## Cite.Software: Centalising Recommendation for Research Stakeholders
+
+*Project Information: [GitHub issues](https://github.com/the-turing-way/the-turing-way/issues?q=is%3Aissue+is%3Aopen+label%3Asoftware-citation)*
+
+- [Christopher Erdmann](https://the-turing-way.netlify.app/afterword/contributors-record#christopher-erdmann)
+- [Malvika Sharan](https://the-turing-way.netlify.app/afterword/contributors-record#malvika-sharan)
+
+## Recognising Research Infrastructure Roles (RIR)
+
+*Project Information: [Article in Journal of Trial & Error](https://journal.trialanderror.org/pub/manifesto-rewarding-recognizing/release/1)*
+
+- [Arielle Bennett](https://the-turing-way.netlify.app/afterword/contributors-record#arielle-bennett)
+- [Esther Plomp](https://the-turing-way.netlify.app/afterword/contributors-record#esther-plomp)
+- [Danny Garside](https://the-turing-way.netlify.app/afterword/contributors-record#danny-garside)
+- [Hao Ye](https://www.weecology.org/author/hao-ye/)
From d60fbaf65f0ac6e97589706b314b290994e0a9bf Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:43 +0000
Subject: [PATCH 006/142] Update source file academic-industry.md
---
book/website/collaboration/academic-industry.md | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/book/website/collaboration/academic-industry.md b/book/website/collaboration/academic-industry.md
index 46149a652a8..a19bdb87252 100644
--- a/book/website/collaboration/academic-industry.md
+++ b/book/website/collaboration/academic-industry.md
@@ -11,6 +11,17 @@
| {ref}`Community Managers: Overview` | Helpful | Beginner | An overview of the Community Manager Role |
| {ref}`Guide to Planning a Community` | Helpful | Beginner | The Guide to Planning a Community are helpful context for the Community Building Subchapter in this section |
+```{figure} ../figures/academic-industry-partnership.*
+---
+height: 500px
+name: academic-industry-partnership
+alt: Scriberia illustration showing the collaboration between academia and industry. On the left hand side is an academic middle-aged man in a suit sitting at a desk with certificates on the wall and a 'world's best prof' mug. On the right hand side is a young professional woman, standing up on the phone with a fancy computer in front of her and sleek looking buildings behind her. Beneath those two panels are the academic man and the industry woman having a conversation- behind them are speech bubbles, a globe and the text 'real-world impact'
+---
+Academic-Industry Partnership
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. Original version on Zenodo. [http://doi.org/10.5281/zenodo.8169292](http://doi.org/10.5281/zenodo.8169292)
+```
+
+
(cl-academic-industry-summary)=
## Summary
Academic-Industry collaborations can take many forms, but put simply they are when an academic institution or university collaborates with a corporation or business such as a pharmaceutical company, a consulting firm or a technology company.
From d0ae9347e525b590e6ec0c0d11867041a40058b7 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:44 +0000
Subject: [PATCH 007/142] Update source file
academic-industry-personal-story.md
---
.../academic-industry-personal-story.md | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/book/website/collaboration/academic-industry/academic-industry-personal-story.md b/book/website/collaboration/academic-industry/academic-industry-personal-story.md
index 6f21016c6a9..f924f7dacab 100644
--- a/book/website/collaboration/academic-industry/academic-industry-personal-story.md
+++ b/book/website/collaboration/academic-industry/academic-industry-personal-story.md
@@ -1,6 +1,16 @@
(cl-academic-industry-personal-story)=
# Turing-Roche Community Activities Personal Story
+```{figure} ../../figures/turing-roche-partnership.jpg
+---
+height: 500px
+name: turing-roche-partnership
+alt: Scriberia illustration showing the journey of the Turing-Roche partnership over 5 years. The image has two people shaking hands showing the collaboration between academia and industry and a road type image showing markers and research themes along the way. The missing data research theme is shown by binary numbers and a missing jigsaw piece and the predictive modelling research theme is illustrated by a crystal ball. At the end of the road are two patients with the text 'improved clinical care'. At the bottom of the image is the text 'better understanding patient and disease heterogeneity' which is the partnership's ultimate aim
+---
+The Turing-Roche Strategic Partnership
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. Original version on Zenodo. [http://doi.org/10.5281/zenodo.8169292](http://doi.org/10.5281/zenodo.8169292)
+```
+
## Introduction
My name is [Vicky Hellon](https://www.turing.ac.uk/people/vicky-hellon) and I am the Community Manager for the Turing-Roche Strategic Partnership.
This 5-year partnership is developing new data science methods to investigate large, complex, clinical and healthcare datasets to better understand how and why patients respond differently to treatment, and how treatment can be improved.
From c85cfffbe2b37b75a7713806aeef0313aae3da56 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:44 +0000
Subject: [PATCH 008/142] Update source file collaboration.md
---
book/website/collaboration/collaboration.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/collaboration.md b/book/website/collaboration/collaboration.md
index 3a9a869cc55..c94b937c8a1 100644
--- a/book/website/collaboration/collaboration.md
+++ b/book/website/collaboration/collaboration.md
@@ -10,7 +10,7 @@ Our work can only reach its highest potential if there are diverse teams of peop
---
name: collaboration
width: 500px
-alt: An iceberg's tip is labelled with the project related technical terms, and a few divers are exploring a huge part of iceberg underwater which are labelled with community oriented collaborative terms
+alt: An iceberg sitting in the sea with the image label above it saying there is more to collaboration than you might think. There is an arrow from the image label pointing to the larger part of the iceberg that is under the sea. A small part of the iceberg is sticking out of the water and has a few people sitting on it. This part of the iceberg is labelled with project related technical terms including the words different teams, common goals, exchange of knowledge and production. There are a few divers exploring the much larger part of the iceberg under the water. This part of the iceberg is labelled with community oriented collaborative terms including treat each other kindly, build diverse teams, code of conduct, inclusive workspace and explicitly open for contribution.
---
There is more to collaboration than we see. _The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
From c9fbe678883de3f59fb071e53d18b6809d2e5327 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:45 +0000
Subject: [PATCH 009/142] Update source file event-participation.md
---
book/website/collaboration/event-participation.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/event-participation.md b/book/website/collaboration/event-participation.md
index fae3bb8332b..842e8ef236e 100644
--- a/book/website/collaboration/event-participation.md
+++ b/book/website/collaboration/event-participation.md
@@ -27,7 +27,7 @@ Test your microphone, webcam, internet bandwidth and compatibility of the softwa
- Check if there is a speaker or chair guidelines, reach out to the organisers if you have not been given one already.
- Prepare your notes or presentation that you will use during your slot as per the guidelines.
- Please consider accessibility and inclusivity when designing your talk, [see this for reference](https://www.w3.org/WAI/teach-advocate/accessible-presentations/#preparing-slides-and-projected-material-speakers).
-- Join social media platforms, like [Slack](https://slack.com), [Twitter](https://twitter.com), [GitHub](https://github.com) or [Gitter](https://gitter.im), that will be used for announcing updates on the event, or facilitate live chat during the event.
+- Join social media platforms, like [Slack](https://slack.com), [X](https://x.com) (formerly Twitter), [GitHub](https://github.com) or [Gitter](https://gitter.im), that will be used for announcing updates on the event, or facilitate live chat during the event.
- To get a head start on networking with other attendees, use the social media platform to introduce yourself.
- Help organisers correct any information that you notice by flagging it, and even better, by supplying the correct information.
From 4e5cdfb2bdaefa1097716e08e0af7b61ac6c5fc5 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:48 +0000
Subject: [PATCH 010/142] Update source file informal-chats.md
---
book/website/collaboration/informal-chats.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/informal-chats.md b/book/website/collaboration/informal-chats.md
index 1558a010b4b..644b83d145b 100644
--- a/book/website/collaboration/informal-chats.md
+++ b/book/website/collaboration/informal-chats.md
@@ -26,7 +26,7 @@ It isn't just fun, their productivity will be higher if they take regular breaks
The first step in running a coffee chat is considering the purpose of the social break, who will be invited and to set the time for the conversation.
Conversations, where *anyone* can join, may be what you want.
-In March 2020, during the COVID-19 pandemic, Kirstie Whitaker hosted [online morning coffee chats on Zoom](https://twitter.com/kirstie_j/status/1239455513080926208?s=20), which she promoted on Twitter.
+In March 2020, during the COVID-19 pandemic, Kirstie Whitaker hosted [online morning coffee chats on Zoom](https://twitter.com/kirstie_j/status/1239455513080926208?s=20), which she promoted on Twitter (now X).
Different people joined at 7:40 am every morning to match her early morning chats at the Turing Institute between when her train arrived and when she usually started working.
The purpose of these calls was to have social contact with anyone else who was up early and looking for motivation to get started.
It didn't matter who came along, everyone was invited to join for 20 minutes.
From 8412e2e4c117f50bdae088775e13463110f53254 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:52 +0000
Subject: [PATCH 011/142] Update source file new-community-guide.md
---
book/website/collaboration/new-community/new-community-guide.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/new-community/new-community-guide.md b/book/website/collaboration/new-community/new-community-guide.md
index 17b41432700..ad00f7c7c67 100644
--- a/book/website/collaboration/new-community/new-community-guide.md
+++ b/book/website/collaboration/new-community/new-community-guide.md
@@ -23,7 +23,7 @@ While reading this chapter, please be aware that you may need to make adjustment
- When leading an open project, use collaborative and open platforms such as [GitHub](http://github.com/) or [GitLab](https://about.gitlab.com/).
- Evaluate the need for any real-time communications, such as if a text chat system like [Slack](https://slack.com) or [Element/Matrix](https://element.io/get-started) will be useful or if a mailing list will be sufficient (read details {ref}`Communication Channels `).
- Consider a separate internal communication platform for your community members and an external one for showing what you’ve done to the rest of the world.
-- A [Twitter account](https://twitter.com) or a simple website (such as on [GitHub pages](https://pages.github.com/)) can be useful external platforms.
+- An [X account](https://x.com) (formerly Twitter) or a simple website (such as on [GitHub pages](https://pages.github.com/)) can be useful external platforms.
- Make sure that the choices of these platforms are made to ensure that there is a low barrier to join them.
(cl-new-community-guide-checklist-proj-summary)=
From 419dae06c9ffc3c872ba1431f788624b92b7d2d7 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:53 +0000
Subject: [PATCH 012/142] Update source file organising-conference.md
---
book/website/collaboration/organising-conference.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/collaboration/organising-conference.md b/book/website/collaboration/organising-conference.md
index 8472a395a42..18746a5e590 100644
--- a/book/website/collaboration/organising-conference.md
+++ b/book/website/collaboration/organising-conference.md
@@ -72,7 +72,7 @@ A few subsections are marked as "Relevant for all phases", as those aspects shou
- Create appropriate channels for the registered participants (general, introduction, social, program).
- Have an announcement channel that can be used for announcing important information by the committee members.
- If the organisation account is not open for others to join, then create an open channel for participants.
-- Create a social media account on Twitter for announcements, branding, improving visibility and wider outreach.
+- Create a social media account on X/Twitter for announcements, branding, improving visibility and wider outreach.
- Assign 1-2 volunteers or committee members who can handle social media in collaboration with the committee.
### Storing and sharing information within the organising committee
@@ -279,7 +279,7 @@ Provide plenty of breaks, and treat those breaks as virtual coffee sessions.*
- Remind the guidelines for participating in discussions.
- Raise hand - on chat, or virtually (like in [Zoom](https://zoom.us/)) or physically.
- Other ways to involve others in the discussion equitably.
-- Ask everyone to write down their name, contact (Twitter, email) and other relevant information.
+- Ask everyone to write down their name, contact (X/Twitter, email) and other relevant information.
- Provide a place to write down pronouns, but keep that optional.
- Start the meeting with an icebreaker question.
- Create opportunities for everyone to share something personal (about their hobby, or experiences) on the document or verbally.
From 397cdd71faf898a701ba7f50cebeec544b8d57cb Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:54 +0000
Subject: [PATCH 013/142] Update source file reg-form-template.md
---
.../collaboration/organising-conference/reg-form-template.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/organising-conference/reg-form-template.md b/book/website/collaboration/organising-conference/reg-form-template.md
index fa5cb76004e..49e77db92b4 100644
--- a/book/website/collaboration/organising-conference/reg-form-template.md
+++ b/book/website/collaboration/organising-conference/reg-form-template.md
@@ -145,7 +145,7 @@ You are encouraged to write in your ethnicity in your own words if you do not id
- How did you hear about our event? (can be an open question or with tick boxes)
- [ ] Website
- [ ] Newsletter
- - [ ] Twitter (add Twitter handle)
+ - [ ] X/Twitter (add X handle)
- [ ] LinkedIn (add LinkedIn account link)
- [ ] In another of our events
- [ ] Direct email
From 1bfc6379cdac2b5d1f29a79b4935e85884083c80 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:56 +0000
Subject: [PATCH 014/142] Update source file research-infrastructure-roles.md
---
.../collaboration/research-infrastructure-roles.md | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/book/website/collaboration/research-infrastructure-roles.md b/book/website/collaboration/research-infrastructure-roles.md
index 12f38a943c3..d368186d3de 100644
--- a/book/website/collaboration/research-infrastructure-roles.md
+++ b/book/website/collaboration/research-infrastructure-roles.md
@@ -1,4 +1,14 @@
(cl-research-infrastructure-roles)=
+
+```{figure} ../figures/researchers-environment.*
+---
+height: 500px
+name: researchers-environment
+alt: The image is a complex amalgamation of people places and things, resembling an urban area with construction happening, in a colour scheme of pink, grey, black, and white. At the top of the image is a header that states "RESEARCHERS" and at the bottom is a footer stating "ENVIRONMENT". The image contains the following. In the top left is a person in a construction crane carrying a series of ones and zeroes wearing a hard-hat looking down. They are labeled "Research Software Engineer". In the bottom left, we see an older male-presenting person with a cane scratching his head looking at a math formula sketched onto the side of a building. Next to them is two pink fluffy rams. One is trapped insight of a light bulb. I hope they manage to escape... This scene is labeled "Research Application Managers". In the top right is a female-presenting person in a pink shirt sketching ones and zeroes onto the side of a bridge who is labeled "Data Steward". In the bottom right is a series of cylinders with little stick figures climbing up ladders to a light bulb that is labeled "Useful Projects". They are being looked upon by a slightly amused looking man with short dark hair.
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
# Research Infrastructure Roles: Introduction
Successful research and scientific collaborations rarely occur without individuals, or teams, taking on the work of structuring participants' interactions, facilitating work, and supporting the impact of the project.
From 035c0aa1485a1431cb74509be20329ab4cc7cd82 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:57 +0000
Subject: [PATCH 015/142] Update source file community-manager.md
---
.../research-infrastructure-roles/community-manager.md | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/book/website/collaboration/research-infrastructure-roles/community-manager.md b/book/website/collaboration/research-infrastructure-roles/community-manager.md
index cbe1edb7f69..fb1b6643ee0 100644
--- a/book/website/collaboration/research-infrastructure-roles/community-manager.md
+++ b/book/website/collaboration/research-infrastructure-roles/community-manager.md
@@ -4,6 +4,16 @@
Community Managers roles are well established in technical industry but only over the last years they have gained recognition within academia and scientific communities.
Often these roles may not be called community managers, but their responsibilities include establishing engagement, organising community spaces and events, supporting people through inclusive practices, developing and maintaining resources, growing and evaluating use cases and collaborating with people involved in research and scientific communities.
+```{figure} ../../figures/research-community-manager.*
+---
+height: 500px
+name: research-community-manager
+alt: Cartoon-like sketch of a person with eight arms. Two are embracing a group of people, while the others are outstretched. The person in the centre is a Research Community Manager, who has eight arms coming out of their shirt. Each arm holds a sign with text describing the main duties of a community manager. They include embedding open, inclusive and reproducible ideas, ensuring a shared understanding, facilitating stakeholder engagement and collaboration, providing technical support; co-creating, maintaining and communicating; and amplifying and championing their community.
+---
+What does a Research Community Manager do?
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.8169292](https://doi.org/10.5281/zenodo.8169292).
+```
+
(cl-infrastructure-community-managers-tasks)=
## What do Community Managers do?
From 8ca32dd66d5fdcd94d8257c1025bcb28bec7999c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:33:57 +0000
Subject: [PATCH 016/142] Update source file data-steward.md
---
.../research-infrastructure-roles/data-steward.md | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/book/website/collaboration/research-infrastructure-roles/data-steward.md b/book/website/collaboration/research-infrastructure-roles/data-steward.md
index 6343030d6ed..8a6c6ee27bf 100644
--- a/book/website/collaboration/research-infrastructure-roles/data-steward.md
+++ b/book/website/collaboration/research-infrastructure-roles/data-steward.md
@@ -4,6 +4,16 @@
Data Stewards are a growing role within scientific communities.
'Data Steward' is an umbrella term for numerous support roles that involve the creation, management and usage of research data (see also the {ref}`rr-rdm` chapter).
+```{figure} ../../figures/data-stewards.*
+---
+height: 400px
+name: data-stewards
+alt: Black, white, grey and purple, cartoon-like sketch of two characters depicted as data stewards in superhero attire, with the left figure gesturing towards symbols of knowledge and alert, and the right figure pointing to tools of the trade such as security and connectivity, all encompassed by a theme of data management and protection.
+---
+A superhero-representation of the core responsibilities of a Data Steward.
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.5706310](https://doi.org/10.5281/zenodo.5706310).
+```
+
(cl-infrastructure-data-stewards-tasks)=
## What do Data Stewards do?
The core responsibilities of a Data Steward can vary, ranging from policy advisor/consultant, to hands-on operational tasks, to technical or ICT-related tasks.
From e93bd122d5c2893579db8b6be52cd61d424afcc6 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:00 +0000
Subject: [PATCH 017/142] Update source file shared-ownership-defaults.md
---
.../collaboration/shared-ownership/shared-ownership-defaults.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/collaboration/shared-ownership/shared-ownership-defaults.md b/book/website/collaboration/shared-ownership/shared-ownership-defaults.md
index 597e87a5d7d..08491490cba 100644
--- a/book/website/collaboration/shared-ownership/shared-ownership-defaults.md
+++ b/book/website/collaboration/shared-ownership/shared-ownership-defaults.md
@@ -23,7 +23,7 @@ The companies that host repositories can - as some do - make it easy to add a li
Plan your project from the beginning to be open throughout the lifecycle of your research.
When using personal or identifiable data, clearly state what measures are taken to ensure privacy and data security.
For everything else in your work, choose an open source license and add it to your repository (see https://choosealicense.com/).
-You can read more about it in the {ref}`Licensing` chapter.
+You can read more about it in the {ref}`Licensing` chapter.
## Meaningful Acknowledgement of Contributors
From 64be3556cd769bcd5dc2a199e1951f79fc319bbb Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:01 +0000
Subject: [PATCH 018/142] Update source file team-manual.md
---
book/website/collaboration/team-manual.md | 23 ++++++++++++-----------
1 file changed, 12 insertions(+), 11 deletions(-)
diff --git a/book/website/collaboration/team-manual.md b/book/website/collaboration/team-manual.md
index aa4215d81fd..75ff17f8a92 100644
--- a/book/website/collaboration/team-manual.md
+++ b/book/website/collaboration/team-manual.md
@@ -78,7 +78,7 @@ What is the social media policy for personal accounts?
How are all the materials made accessible (image descriptions - see {ref}`ch-style-figures-alttext`, translations)?
How is the lab involved in the department? How does the lab work with participants?
- Publications: What needs to happen before a paper is published? what are the preprint policies?
-What are the journal preferences? How does the lab deal with authorship({ref}`cm-aa`)?
+What are the journal preferences? How does the lab deal with authorship ({ref}`cm-aa`)?
see {cite:ps}`Liboiron2017equity` and {cite:ps}`Chawla2018assigning` for author order discussions.
- Consider academic citation practices. [Who do you choose to link and re-circulate in your work? Who gets erased? Who should you stop citing?](http://www.criticalethnicstudiesjournal.org/citation-practices)
- Conferences:
@@ -163,7 +163,7 @@ See also Patrick Lencioni's 'Teamwork: The Five Dysfunctions of a Team' ({cite:p
(cl-team-manual-assess)=
## How to assess your lab culture?
* Leslie Vosshall's [lab survey](https://docs.google.com/forms/d/e/1FAIpQLScGCi7iACgmVBhFcE7G90oPwuTs-g9CQkrDmOUoQ4FvoT9CfA/viewform) to measure whether your lab is happy
-* {cite:ps}`Hernandez2021improving`
+* [Improving lab culture through self-assessment: a case study](https://doi.org/10.1101/2021.12.08.471870) {cite:ps}`Hernandez2021improving`
(cl-team-manual-examples)=
## Examples of Team Manuals
@@ -187,18 +187,19 @@ See also Patrick Lencioni's 'Teamwork: The Five Dysfunctions of a Team' ({cite:p
* Non-scientific approaches to internal collaboration: [Oxide's Request-for-discussion process template](https://oxide.computer/blog/rfd-1-requests-for-discussion), modelled after the original spirit of the [Request for Comments](https://en.wikipedia.org/wiki/Request_for_Comments) process
## Credit
-This summary is based on a [Twitter Thread by @samuelmehr](https://twitter.com/samuelmehr/status/1139733291899080705) ([Webarchive](https://web.archive.org/web/20190615104618/https://twitter.com/samuelmehr/status/1139733291899080705)), as well as discussions during the [Open Science Retreat 2023](https://open-science-retreat.gitlab.io).
+This summary is based on an [X (formerly Twitter) Thread by @samuelmehr](https://twitter.com/samuelmehr/status/1139733291899080705) ([Webarchive](https://web.archive.org/web/20190615104618/https://twitter.com/samuelmehr/status/1139733291899080705)), as well as discussions during the [Open Science Retreat 2023](https://open-science-retreat.gitlab.io).
(cl-team-manual-resources)=
## Additional Resources on improving Research Culture
* [Research Culture - UKRIO Webinar](https://www.youtube.com/watch?v=WH2cAChUzFA)
-* [How to grow a healthy lab](https://www.nature.com/collections/pmlcrkkyyq), including {cite:ps}`Norris2018health`.
-* {cite:ps}`Andreev2022welcome`
+* [Research Culture: Why every lab needs a handbook](https://doi.org/10.7554/eLife.88853) {cite:ps}`Tendler2023culture`
+* [How to grow a healthy lab](https://www.nature.com/collections/pmlcrkkyyq), [including Health tips for research groups](https://doi.org/10.1038/d41586-018-05146-5) {cite:ps}`Norris2018health`.
+* [Welcome to the lab](https://doi.org/10.7554/elife.79627) {cite:ps}`Andreev2022welcome`
* [Guidelines Toward Inclusive Practices in Academics by eLife Community Ambassadors](https://osf.io/muk7v/wiki/home/)
-* {cite:ps}`Maestre2019ten`
-* {cite:ps}`Greene2021safety`
-* {cite:ps}`Chaudhary2020ten`
-* {cite:ps}`Pike2022simple`
-* {cite:ps}`RuedasGracia2022ten`
-* {cite:ps}`Rillig2022ten`
+* [Ten simple rules towards healthier research labs](https://doi.org/10.1371/journal.pcbi.1006914) {cite:ps}`Maestre2019ten`
+* [Safety and belonging in the field: a checklist for educators](https://doi.org/10.31223/x53p6h) {cite:ps}`Greene2021safety`
+* [Ten simple rules for building an antiracist lab](https://doi.org/10.1371/journal.pcbi.1008210) {cite:ps}`Chaudhary2020ten`
+* [10 simple rules for a supportive lab environment](https://doi.org/10.1162/jocn_a_01928) {cite:ps}`Pike2022simple`
+* [Ten simple rules for creating a sense of belonging in your research group](https://doi.org/10.1371/journal.pcbi.1010688) {cite:ps}`RuedasGracia2022ten`
+* [Ten simple rules for how you can help make your lab a better place as a graduate student or postdoc](https://doi.org/10.1371/journal.pcbi.1010673) {cite:ps}`Rillig2022ten`
* [Building a culture of open and reproducible science](https://www.youtube.com/watch?v=__PNXPl2xq0&list=PLeDygc8TN_J6h3RbDDVPW5oTJzRBVg7BQ&index=3&t=3472s)
From 07101e069a30b8f7ee8dd52ce69783ecdbf82d71 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:01 +0000
Subject: [PATCH 019/142] Update source file team-manual-on-off-boarding.md
---
.../team-manual-on-off-boarding.md | 51 +++++++++++++++++++
1 file changed, 51 insertions(+)
create mode 100644 book/website/collaboration/team-manual/team-manual-on-off-boarding.md
diff --git a/book/website/collaboration/team-manual/team-manual-on-off-boarding.md b/book/website/collaboration/team-manual/team-manual-on-off-boarding.md
new file mode 100644
index 00000000000..ac665d3922c
--- /dev/null
+++ b/book/website/collaboration/team-manual/team-manual-on-off-boarding.md
@@ -0,0 +1,51 @@
+(cl-team-manual-on-off-boarding)=
+# On- and offboarding team members
+
+Having clear onboarding processes ensure that group members are off to a good start in the lab.
+Offboarding processes ensure that everything is taken care off when lab members leave for a future step.
+The on- and offboarding checklists below provide some pointers on how to set up the on/off boarding checklists of your group, that can be a part of your {ref}`Team Manual `.
+
+(cl-team-manual-on-boarding)=
+## Onboarding Checklist
+* Review relevant documents provided in a main resource such the {ref}`Team Manual `.
+Information may include:
+ * List of team members, their roles and projects
+ * Institutional policies as well as participation guidelines of the research group, institute, funder or country.
+ * Code of Conduct and reporting mechanism.
+ * Point of contacts for IT, HR, data protection, legal, communications or other teams who you might need to connect for different purposes.
+ * Authorship and contributorship guidelines.
+* Check whether the team has a {ref}`Data Management Plan` or whether you need to set this up yourself
+ * Review your storage options and access to software and tools such as {ref}`Electronic Lab Notebooks`.
+ * Especially when working with {ref}`sensitive data` it is important to familiarise new team members with the recommended practices.
+ * Consider options for long term storage and data sharing
+* Set up documentation for your workflows (lab notes, project repository, README files) based on the recommendations provided by your team (ideally outlined in the Team Manual or Data management Plan).
+ * Check whether there are existing templates that can be reused.
+* Ensure access to all needed facilities (lab pass, keys, folders, storage locations).
+* If any of this information is not clear, provide feedback on the onboarding process to improve it for future lab members!
+
+(cl-team-manual-off-boarding)=
+## Offboarding Checklist
+
+* Research objects are publicly shared via an appropriate data repository
+* Research objects that are not publicly shared are stored internally and responsibilities have been transferred, including access to documentation (READme files or labnotes) and ethical approvals.
+* Research objects that are dispensable are cleaned up to avoid unnecessary storage clutter and confusion.
+* The content of the Data Management Plan has been transferred, so that data can be found and reused within the research team.
+* It is clear which physical reagents are relevant and where they are stored - irrelevant reagents have been cleaned up.
+* Contact details for the future are provided - other personal data is removed
+* Have an exit meeting with supervisor/department head or HR.
+* Return any borrowed property (keys, passes, equipment).
+* The leaving lab member can be provided with a statement that describes their contributions during their employment, instead of having to rely on future reference letters.
+
+(cl-team-manual-off-boarding-example)=
+### Examples
+
+- [example offboarding checklist](https://doi.org/10.5281/zenodo.7520527)
+
+(cl-team-manual-on-off-boarding-resources)=
+## More information
+* [Harvard on and offboarding lists](https://osf.io/pw7ed/)
+* Research Data
+ * [Research Data Exit Checklist](http://hdl.handle.net/2142/111616)
+ * [Project Close-Out Checklist for Research Data](https://resolver.caltech.edu/CaltechAUTHORS:20200519-142758925)
+ * [Data Departure checklist](https://doi.org/10.7907/h314-4x51)
+* [It takes a laboratory to avoid data loss](https://www.nature.com/articles/d41586-022-02967-3)
From 309214a7752dfc0cd8b11c933786679fc90f727f Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:03 +0000
Subject: [PATCH 020/142] Update source file aa-stories-community.md
---
book/website/communication/aa/aa-stories-community.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/website/communication/aa/aa-stories-community.md b/book/website/communication/aa/aa-stories-community.md
index 922a0d4d0b5..6f614b3880a 100644
--- a/book/website/communication/aa/aa-stories-community.md
+++ b/book/website/communication/aa/aa-stories-community.md
@@ -7,12 +7,12 @@ Brainhack is an open science community that has an innovative meeting format to
Remi, Isil and their colleagues have been dealing with the issue of how to determine contributions and authorship in such a large community.
**More information about Remi Gau:**
-* [Website](https://remi-gau.github.io/)
-* [Twitter](https://twitter.com/RemiGau?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor)
+* Website: [remi-gau.github.io](https://remi-gau.github.io/)
+* X (formerly Twitter): [RemiGau](https://twitter.com/RemiGau)
**More information about Isil Poyraz Bilgin:**
-* [Github](https://github.com/complexbrains)
-* [Twitter](https://twitter.com/complexbrains)
+* GitHub: [complexbrains](https://github.com/complexbrains)
+* X (formerly Twitter): [complexbrains](https://twitter.com/complexbrains)
**1. What is the *normal* practice of authorship for academic papers in your discipline? or used to be the normal practice?**
From c8717dc5f951207583426bbf83ec8125e54fa036 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:04 +0000
Subject: [PATCH 021/142] Update source file aa-stories-interdisciplinary.md
---
.../communication/aa/aa-stories-interdisciplinary.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/book/website/communication/aa/aa-stories-interdisciplinary.md b/book/website/communication/aa/aa-stories-interdisciplinary.md
index 5fcae0279f7..8d67a6f8471 100644
--- a/book/website/communication/aa/aa-stories-interdisciplinary.md
+++ b/book/website/communication/aa/aa-stories-interdisciplinary.md
@@ -10,13 +10,13 @@ It brings together an interdisciplinary group of researchers from a range of dis
### Find out more about their work below:
**Federico Nanni:**
-* [ORCID](https://orcid.org/0000-0003-2484-4331)
-* [Twitter](https://twitter.com/f_nanni)
-* [Website](https://github.com/fedenanni)
+* ORCID: [0000-0003-2484-4331](https://orcid.org/0000-0003-2484-4331)
+* X (formerly Twitter): [f_nanni](https://twitter.com/f_nanni)
+* GitHub: [fedenanni](https://github.com/fedenanni)
**Mariona Coll Ardanuy**
-* [ORCID](http://orcid.org/0000-0001-8455-7196)
-* [Website](https://github.com/mcollardanuy)
+* ORCID: [0000-0001-8455-7196](http://orcid.org/0000-0001-8455-7196)
+* GitHub: [mcollardanuy](https://github.com/mcollardanuy)
**1. What is the *normal* practice of authorship for academic papers in your discipline? or used to be the normal practice?**
From 67c7829b55a6954b0755303fa0bf2a2dc8cbd028 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:07 +0000
Subject: [PATCH 022/142] Update source file blogs.md
---
book/website/communication/blogs.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/communication/blogs.md b/book/website/communication/blogs.md
index 62f11facbe2..ad56dd19a27 100644
--- a/book/website/communication/blogs.md
+++ b/book/website/communication/blogs.md
@@ -55,7 +55,7 @@ Get your blog noticed.
* It's a good idea to tell your target audience about your blog and again each time you release a post.
* Use mailing lists from key associations linked to your research.
-* Use social media such as Twitter or Facebook.
+* Use social media such as X (formerly Twitter) or Facebook.
* Ask colleagues to retweet or send out emails to advertise your blog.
## Analysing the Impact
From 6ea5d46e2209c069e00c6a1b902b97de9377f976 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:07 +0000
Subject: [PATCH 023/142] Update source file blogs-personal-stories.md
---
book/website/communication/blogs/blogs-personal-stories.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/communication/blogs/blogs-personal-stories.md b/book/website/communication/blogs/blogs-personal-stories.md
index 781212fbba9..b547cdc5ed9 100644
--- a/book/website/communication/blogs/blogs-personal-stories.md
+++ b/book/website/communication/blogs/blogs-personal-stories.md
@@ -7,7 +7,7 @@
You can find out more about her work from the links below:
* Personal website: [veronikach.com](https://veronikach.com/)
-* Twitter: [@DrVeronikaCH](https://twitter.com/DrVeronikaCH)
+* X (formerly Twitter): [DrVeronikaCH](https://twitter.com/DrVeronikaCH)
* ORCID: [0000-0003-0176-9324](https://orcid.org/0000-0003-0176-9324)
We would like to thank **Dr Veronika Cheplygina** for answering our interview questions about her very successful blog series called ['How I fail'](https://veronikach.com/failure/).
From fb480a21bdf45725ac5c483fc4e02a6727067f18 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:09 +0000
Subject: [PATCH 024/142] Update source file citable-cite.md
---
.../communication/citable/citable-cite.md | 21 +++++++++++++++++--
1 file changed, 19 insertions(+), 2 deletions(-)
diff --git a/book/website/communication/citable/citable-cite.md b/book/website/communication/citable/citable-cite.md
index f6b521c4a3b..134e24a7eee 100644
--- a/book/website/communication/citable/citable-cite.md
+++ b/book/website/communication/citable/citable-cite.md
@@ -25,6 +25,8 @@ See also [FORCE11 resource](https://www.force11.org/node/4771).
## Citing Data
When sharing a dataset, use the assigned DOI (from the data repository) and add this to your data availability statement at the end of the paper (similar to the acknowledgement section).
It is important to also cite your dataset in the references themselves, as only the citations in the reference section will contribute to citation counts.
+Data citation is important because it facilitates access, transparency and potentially reproducibility, reuse, and credit for researchers.
+It also provides recognition and visibility for the repositories that share data.
You can find examples of these statements in the publishers' (research data) author policies.
@@ -45,6 +47,9 @@ You can find examples of these statements in the publishers' (research data) aut
- “The data that support the findings of this study are available upon request.
Access conditions and procedures can be found at [URL to restricted access repository such as [EASY](https://easy.dans.knaw.nl/ui/home).]”
+**When code is shared:**
+- Data and code to reproduce the results shown in the paper can be obtained from The Turing Way (2023) at Zenodo ([https://zenodo.org/doi/10.5281/zenodo.3233853](https://zenodo.org/doi/10.5281/zenodo.3233853)) and GitHub ([https://github.com/the-turing-way/the-turing-way](https://github.com/the-turing-way/the-turing-way)). We used R version 4.2.2 (*use citation() to check the suggested citation*) and the following R packages: ggplot2 ([Wickham 2016](https://cran.r-project.org/web/packages/ggplot2/citation.html)), another example (*and citation added to the references!*).
+
**More Data Availability Statement examples:**
You can find more examples on the [Manchester's Data Access Statements page](https://www.library.manchester.ac.uk/using-the-library/staff/research/research-data-management/sharing/data-access-statements/), the [Cambridge Data Availability Statement examples](https://www.cambridge.org/core/services/authors/open-data/data-availability-statements), the [AMS Data Availability Statement examples](https://www.ametsoc.org/index.cfm/ams/publications/author-information/formatting-and-manuscript-components/data-availability-statement-examples/), or [Nature's Tips for writing a dazzling Data Availability Statement](https://researchdata.springernature.com/posts/tips-for-writing-a-dazzling-das-data-availability-statement).
@@ -54,6 +59,7 @@ You can find more examples on the [Manchester's Data Access Statements page](htt
A software citation has a lot of the same elements as a data citation, described above, and are described in more detail in the [Software Citation Principles](https://www.force11.org/software-citation-principles).
When using others software, it is vital to cite and attribute it properly.
+See also [How to Cite R and R Packages](https://ropensci.org/blog/2021/11/16/how-to-cite-r-and-r-packages/) for more information.
::::{tab-set}
:::{tab-item} GitHub
@@ -62,19 +68,30 @@ To make your code citable, you can use the integration between [Zenodo](https://
- Create a file to tell people how to cite your software. Use this [handy guide](https://citation-file-format.github.io/cff-initializer-javascript/) to format the file.
- Link your GitHub account with a Zenodo account. This guide explains [how](https://guides.github.com/activities/citable-code/).
-- You can tell Zenodo what information or metadata you want to include with your software by adding a `zenodo.json` file, described [here](https://guide.esciencecenter.nl/#/citable_software/making_software_citable).
+- You can tell Zenodo what information or metadata you want to include with your software by converting your `CITATION.cff` file to `zenodo.json`.
+
+ ```bash
+ pip install cffconvert
+ cffconvert --validate
+ cffconvert --format zenodo --outfile .zenodo.json
+ ```
+
+- Add `.zenodo.json` to your repository.
- On Zenodo, flip the switch to the 'on' position for the GitHub repository you want to release.
- On GitHub, click the *Create a new release* button.
Zenodo should automatically be notified and should make a snapshot copy of the current state of your repository (just one branch, without any history), and should also assign a persistent identifier (DOI) to that snapshot.
- Use the DOI in any citations of your software and tell any collaborators and users to do the same!
+
:::
:::{tab-item} GitLab
:sync: gitlab_tab
+
+
To make your code citable, through an automated publication of your Gitlab repository to [Zenodo](https://zenodo.org/):
- Create a file to tell people how to cite your software. Use this [handy guide](https://citation-file-format.github.io/cff-initializer-javascript/) to format the file.
-- Convert your `citation.cff` file to `.zenodo.json`.
+- Convert your `CITATION.cff` file to `.zenodo.json`.
This file tells Zenodo what information or metadata you want to include with your software.
```bash
From e2881a1d5ba12c5afe2108b7249ede18dc453096 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:10 +0000
Subject: [PATCH 025/142] Update source file citable-resources.md
---
book/website/communication/citable/citable-resources.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/communication/citable/citable-resources.md b/book/website/communication/citable/citable-resources.md
index 12719c70ad6..d7d1deb58a0 100644
--- a/book/website/communication/citable/citable-resources.md
+++ b/book/website/communication/citable/citable-resources.md
@@ -31,5 +31,5 @@
- [FORCE11 Data Citation principles](https://www.force11.org/datacitationprinciples)
- [FORCE11 Software Citation principles](https://www.force11.org/software-citation-principles)
- [Getting Started with your ORCID record](https://support.orcid.org/hc/en-us/articles/360006896894-Getting-started-with-your-ORCID-record)
-- [Making software citeable](https://guide.esciencecenter.nl/citable_software/making_software_citable.html)
+- [Making software citeable](https://the-turing-way.netlify.app/communication/citable/citable-cite#citing-software)
- [OpenAIRE Guide on Person Identifiers](https://www.openaire.eu/how-can-identifiers-improve-the-dissemination-of-your-research-outputs)
From 076add6f55e53be3080782b1b32f5644e1133862 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:11 +0000
Subject: [PATCH 026/142] Update source file comms-overview-resources.md
---
.../communication/comms-overview/comms-overview-resources.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/communication/comms-overview/comms-overview-resources.md b/book/website/communication/comms-overview/comms-overview-resources.md
index 00865513ca1..1833c4ce961 100644
--- a/book/website/communication/comms-overview/comms-overview-resources.md
+++ b/book/website/communication/comms-overview/comms-overview-resources.md
@@ -82,9 +82,9 @@ Video conferencing platforms such as Zoom or Google meet also have captions.
Read more in this chapter: {ref}`cm-social-media`.
-* [Tweetdeck](https://tweetdeck.twitter.com/)
+* [X Pro (formerly Tweetdeck)](https://help.twitter.com/en/using-x/how-to-use-x-pro)
* [Buffer](https://buffer.com/)
-* This is a good [guide to getting set up on Twitter](https://www.wired.com/story/how-to-setup-twitter-search-hashtag-and-login-help/).
+* This is a good [guide to getting set up on X (formerly Twitter)](https://www.wired.com/story/how-to-setup-twitter-search-hashtag-and-login-help/).
* [Ten simple rules to getting started on Twitter as a scientist](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1007513)
* [Ten simple rules of live-tweeting at scientific conferences](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003789)
* [How to use Twitter to further your research career](https://www.nature.com/articles/d41586-019-00535-w)
From ca764953b2e7b102657a9dde184a5b9dc7837df6 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:14 +0000
Subject: [PATCH 027/142] Update source file lay-summaries-personal-stories.md
---
.../lay-summaries/lay-summaries-personal-stories.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/communication/lay-summaries/lay-summaries-personal-stories.md b/book/website/communication/lay-summaries/lay-summaries-personal-stories.md
index 8f8da53a5cf..336fc9d8897 100644
--- a/book/website/communication/lay-summaries/lay-summaries-personal-stories.md
+++ b/book/website/communication/lay-summaries/lay-summaries-personal-stories.md
@@ -8,8 +8,8 @@ She is currently leading a project concerning the FAIRification of phytolith dat
Find out more about her work from the links below:
* [FAIR Phytoliths Project Website](https://open-phytoliths.github.io/FAIR-phytoliths/)
-* Blog - [The Open Archaeobotanist](https://ekaroune.github.io/The-Open-Archaeobotanist/)
-* Twitter - [ekaroune](https://twitter.com/ekaroune)
+* Blog: [The Open Archaeobotanist](https://ekaroune.github.io/The-Open-Archaeobotanist/)
+* X (formerly Twitter): [ekaroune](https://twitter.com/ekaroune)
We would like to thank **Emma** for answering our interview questions about her work with [PalaeoSIG](https://www.britishecologicalsociety.org/membership-community/special-interest-groups/palaeoecology-group/), the special interest group for palaeoecology at the British Ecological Society.
From 2c1a7bc868e26ea60638665053880180a06cd26a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:15 +0000
Subject: [PATCH 028/142] Update source file education.md
---
book/website/communication/open/education.md | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/book/website/communication/open/education.md b/book/website/communication/open/education.md
index 4848b7f6cd7..35b09c944f0 100644
--- a/book/website/communication/open/education.md
+++ b/book/website/communication/open/education.md
@@ -19,7 +19,7 @@ Open Education is rooted in the human right to access high-quality education.
- Easier to collaborate, participate and share resources.
- **Reduces duplication of effort**: If an educator needs materials for teaching and they can access open materials, then they need not make their own from scratch, thereby saving time.
- Is generally **more accessible** due to the use of open formats compared to proprietary formats in which files cannot be changed.
- - Formats like Microsoft docx require access to Microsoft Word, whereas open formats such as RTF and HTML work with a variety of software.
+ - Formats like Microsoft docx are proprietary, so preference should be given to open formats such as ODT and HTML work with a variety of software.
- While .pdf is an open format, it is also more closed in the sense that it is difficult to edit compared to formats such as RTF and HTML.
- Accessibility is not guaranteed!
Learn more about how to improve the accessibility of your resources:
@@ -61,9 +61,13 @@ Fully open OERs comply with the [5 Rs](http://opencontent.org/definition/):
## How to set up OERs?
1. Choose a platform.
-2. Collect resources under an open license (see [Attribution & Fair Use: Copyright in Open Education](https://www.youtube.com/watch?v=jGTUHdadqJU) and {ref}`Licensing data section` for more information).
-3. Ask for feedback.
-4. Share and promote your resources.
+2. Collect resources under an open license
+ For more information, see:
+ - [Attribution & Fair Use: Copyright in Open Education](https://www.youtube.com/watch?v=jGTUHdadqJU)
+ - [Copyright ownership in higher education and potential implications for Open Education](https://doi.org/10.17161/jcel.v5i1.14946) by {cite:ps}`Gumb2022oer`
+ - and {ref}`Licensing data section`
+4. Ask for feedback.
+5. Share and promote your resources.
See also a short video on '[Creating Open Educational Resources: Tips for New Creators](https://www.youtube.com/watch?v=DV-HiWtMq1U)' and '[A Guide to Making Open Textbooks with Students](https://press.rebus.community/makingopentextbookswithstudents/)'
@@ -76,9 +80,12 @@ See also a short video on '[Creating Open Educational Resources: Tips for New Cr
(cm-open-education-resources)=
# Resources
- [SPARC Open Education Leadership Program curriculum](https://sparcopen.org/our-work/open-education-leadership-program/curriculum/)
+- [The OER Starter Kit ](https://iastate.pressbooks.pub/oerstarterkit/)
- [Open Education Group](https://openedgroup.org/)
- [Open Education Network](https://open.umn.edu/oen/)
+- [Open Educational Resources](https://www.surrey.ac.uk/library/open-research/open-educational-resources) by the University of Surrey
- Webinar on '[Creating and Sharing Open Educational Resources (OER)](https://www.youtube.com/watch?v=6JgoUbED4rM)'
+- Webinar on '[Another Kind of Open: exploring the benefits and barriers to the creation and use of open educational resources](https://www.youtube.com/watch?v=Mc7eV4gHA_0)'
- [Podcast interview with Nicole Allen](https://leadinglinespod.com/episodes/episode-029-nicole-allen/)
- Video Session on '[Open Education Through an Ethics of Care & Justice](https://www.youtube.com/watch?v=i74KEAJnoPY)'
- Book 'Teaching to transgress' by bell hooks.
From d4d3905ea0cad104973a49a62da262eb440ba967 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:16 +0000
Subject: [PATCH 029/142] Update source file os-comms-channels.md
---
book/website/communication/os-comms/os-comms-channels.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/communication/os-comms/os-comms-channels.md b/book/website/communication/os-comms/os-comms-channels.md
index 2bf4388d7ae..f224ffe9d7d 100644
--- a/book/website/communication/os-comms/os-comms-channels.md
+++ b/book/website/communication/os-comms/os-comms-channels.md
@@ -14,7 +14,7 @@ When setting up your communication channels, there are some important things to
* Can users control or filter what kind of information they receive?
There are three commonly used channels: mailing lists (such as [Topicbox](https://www.topicbox.com/) or [Google groups](https://support.google.com/mail/thread/14635045?hl=en)), community forums (such as [Vanilla Forum](https://vanillaforums.com/en/software/) or [Discourse](https://www.discourse.org/)) and chats (such as [Gitter](https://gitter.im/) or [Slack](https://app.slack.com/signin)).
-Besides these, many communities also use platforms for weekly or monthly newsletters, blogs, and social media on [Twitter](https://twitter.com/) or [Facebook](https://www.facebook.com/).
+Besides these, many communities also use platforms for weekly or monthly newsletters, blogs, and social media on [X (formerly Twitter)](https://x.com/) or [Facebook](https://www.facebook.com/).
In the table below, some properties of the first three communication platforms have been highlighted, which will allow open source project leaders to choose the most appropriate channels for their communities.
From 81e91a781c0ddfa099d94aba2923d56d99e95ac5 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:17 +0000
Subject: [PATCH 030/142] Update source file peer-review-open.md
---
.../communication/peer-review/peer-review-open.md | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/book/website/communication/peer-review/peer-review-open.md b/book/website/communication/peer-review/peer-review-open.md
index 5884c809581..fa9b9b0e5b2 100644
--- a/book/website/communication/peer-review/peer-review-open.md
+++ b/book/website/communication/peer-review/peer-review-open.md
@@ -1,6 +1,15 @@
(cm-pr-open)=
# Open Peer Review
+```{figure} ../../figures/open-peer-review.*
+---
+height: 500px
+name: open-peer-review
+alt: Cartoon-like sketch, in black and white with orange shading, of a three tiered cake with the title Open Peer Review at the top. On the bottom level of the cake is the word collaboration with different types of people standing on this level of the cake looking thoughtful. Each person has a speech bubble over them with an eye in it. There are more thoughtful people standing on the second tier and the third and top tier has three people holding a written document with the words supporting quality over them. At the side of the cake are the words recognition, on the left side, and content and process, on the right side.
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
## What is Open Peer Review?
Open Peer review can refer to various practises, including signing your review, publishing reviews along with the paper, and allowing for the community to contribute to the peer review process ([Open Science Community Utrecht](https://openscience-utrecht.com/peer-review)). Below some different types of Open Peer Review are highlighted, as well as the benefits of opening up the peer review process.
@@ -56,3 +65,7 @@ The ability of double-anonymized review to address biases in peer review remains
* [F1000](https://f1000research.com/)
* [Open Research Europe](https://open-research-europe.ec.europa.eu)
* [SciPost](https://scipost.org/)
+* [Peer Community In](https://peercommunityin.org/)
+
+
+
From d9a0229716244d013023651795b9a980ffe3a570 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:19 +0000
Subject: [PATCH 031/142] Update source file presentations-personal-stories.md
---
.../presentations/presentations-personal-stories.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/book/website/communication/presentations/presentations-personal-stories.md b/book/website/communication/presentations/presentations-personal-stories.md
index ab9bd41f256..a2b4688acf7 100644
--- a/book/website/communication/presentations/presentations-personal-stories.md
+++ b/book/website/communication/presentations/presentations-personal-stories.md
@@ -5,7 +5,7 @@ We would like to thank **[Yanina Bellini Saibene](https://yabellini.netlify.app/
Find out more about her work here:
* ORCID: [0000-0002-4522-7466](https://orcid.org/0000-0002-4522-7466)
-* Twitter: [@yabellini](https://twitter.com/yabellini)
+* X (formerly Twitter): [yabellini](https://twitter.com/yabellini)
**Yanina** is a researcher at [INTA in La Pampa, Argentina](https://inta.gob.ar/personas/bellini.yanina), applying data science to the agricultural sector.
She has a degree in Information Systems and a Master in Data Mining and Knowledge Management.
@@ -151,8 +151,8 @@ I hope to continue learning; currently, I am reading a couple of books that I ho
Queremos agradecer a **[Yanina Bellini Saibene](https://yabellini.netlify.app/es/)** por responder nuestras preguntas.
Podés interiorizarte en su trabajo en los siguientes links:
-* [ORCID](https://orcid.org/0000-0002-4522-7466)
-* [Twitter](https://twitter.com/yabellini)
+* ORCID: [0000-0002-4522-7466](https://orcid.org/0000-0002-4522-7466)
+* X (formerly Twitter): [yabellini](https://twitter.com/yabellini)
**Yanina** es investigadora del [INTA en La Pampa, Argentina](https://inta.gob.ar/personas/bellini.yanina) aplicando ciencia de datos al sector agropecuario.
Es Licenciada en Sistemas de Información y Magíster en Explotación de Datos y Gestión del Conocimiento.
From 79cdc46d7f28187bafd97d9dab664c27ad19b8d7 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:20 +0000
Subject: [PATCH 032/142] Update source file social-media.md
---
book/website/communication/social-media.md | 40 +++++++++++-----------
1 file changed, 20 insertions(+), 20 deletions(-)
diff --git a/book/website/communication/social-media.md b/book/website/communication/social-media.md
index 206291839b8..73cf612c131 100644
--- a/book/website/communication/social-media.md
+++ b/book/website/communication/social-media.md
@@ -20,40 +20,40 @@ Although, maintaining a social media account successfully can be time-consuming.
(cm-social-media-platforms)=
## Social Media Platforms
-You could use academic-based social media sites such as ResearchGate or Academia.edu or more general ones such as Twitter, Facebook, Instagram, Youtube and Linkedin.
+You could use academic-based social media sites such as ResearchGate or Academia.edu or more general ones such as X (formerly Twitter), Facebook, Instagram, Youtube and LinkedIn.
More than 20 million researchers (figure from spring 2021) have signed up to ResearchGate and it can therefore offer a great opportunity for sharing papers, connecting with colleagues through the messaging feature and can be used to advertise projects.
-There are similar benefits to using Academia.edu or Mendeley, although they are not used as much as Researchgate.
+There are similar benefits to using Academia.edu or Mendeley, although they are not used as much as ResearchGate.
A regular criticism of these sites is the spamming of your email with constant updates that are hard to turn off.
-More general social media sites are very popular with academic audiences and a recent Nature survey {cite:ps}`Noorden2014social` highlighted that researchers mostly use Twitter and Linkedin for professional use rather than Facebook.
+More general social media sites are very popular with academic audiences and a Nature survey in 2014 {cite:ps}`Noorden2014social` highlighted that researchers mostly use X and LinkedIn for professional use rather than Facebook.
-This survey also showed that Twitter had a wider range of uses compared to the other social media platforms, such as following discussions, posting work content, discovering peers, discovering recommended papers and commenting on others research.
+This survey also showed that X had a wider range of uses compared to the other social media platforms, such as following discussions, posting work content, discovering peers, discovering recommended papers and commenting on others research.
It has become the communication channel of choice for many researchers and is opening up research discussions at a much earlier stage than previously seen.
-Twitter can be used to build up a personal academic profile, for use throughout a research project and can also be used by organisations to promote their work and message.
-It can make research more visible and understandable to wider communities by allowing non-scientists to find new research instantaneously.
+X can be used to build up a personal academic profile, for use throughout a research project and can also be used by organisations to promote their work and message.
Scientists can also be contacted directly by the public, which enables a more approachable level of communication {cite:ps}`Kelesidou2021scicomm`.
+However recent changes to the platform have also alienated some academics and in the longer term this may result in a more widespread move by researchers away from X to more open platforms {cite:ps}`VidalValero2023twitter,Hiltzik2023twitter`.
-Due to its popularity and wide range of uses for academic purposes, the next two sub-chapters focus on using Twitter.
-However, below is an overview of the most popular general social media sites used by researchers - Twitter, Linkedin, Facebook and Instagram.
+Despite this X remains popular and, given its wide ranging uses for academic purposes, the next two sub-chapters focus on how to use it effectively.
+Below we also offer a brief overview of the most popular general social media sites used by researchers - X, LinkedIn, Facebook and Instagram.
-### Twitter
+### X (formerly Twitter)
-* They have 353 million monthly active users.
+* They have 393 million monthly active users as of September 2023 {cite:ps}`Hays2023twitter`.
* It is less formal than other platforms and very popular with academic audiences.
-* Character limit is small, only 280. But you can join tweets in threads.
+* Character limit is only 280 unless you pay for X Premium, but you can join tweets in threads.
* You can tag others in your tweets or photos.
-* You can add links, photos (size 1200 x 628 pixels) and videos (max 2 minutes 20 seconds) in tweets. You can also add links to videos.
+* You can add links, photos and videos (max 2 minutes 20 seconds) in tweets. You can also add links to videos.
* If you don't have an image, adding a link will generate a preview image.
* It is a conversational and chatty platform. So be chatty in tweets and use images and gifs to make your tweets more fun.
-### Linkedin
+### LinkedIn
-* They have 250 million monthly active users.
-* It is a more formal and professional communication channel than Twitter and Facebook.
-* Character limit is larger than Twitter at 63,206.
+* They have 930 million monthly active users as of February 2023 {cite:ps}`Aslam2023linkedin`.
+* It is a more formal and professional communication channel than X and Facebook.
+* Character limit is larger than X at 63,206.
* You can tag others in your posts.
* You can add links, photos (size 1200 x 628 pixels) and videos (max 10 minutes) in posts.
* It is used as an interactive CV, for recruitment and professional networking.
@@ -63,8 +63,8 @@ However, below is an overview of the most popular general social media sites use
### Facebook
-* They have 2.8 billion monthly active users.
-* Character limit the same as Linkedin at 63,206.
+* They have 3.03 billion monthly active users as of June 2023 {cite:ps}`Meta2023facebook`.
+* Character limit the same as LinkedIn at 63,206.
* You can add tags to other users.
* You can add links, photos (size 1200 x 628 pixels) and videos (up to 240 minutes and max 4GB size file) to your posts.
* It is a community-based platform so you have to create that community and be relevant to it.
@@ -73,9 +73,9 @@ So it's not the best platform for professional organisations.
### Instagram
-* They have 1.2 billion monthly active users.
+* They have 2 billion monthly active users as of December 2021 {cite:ps}`Rodriguez2023instagram`.
* Character limit is 2,200.
-So larger than Twitter but less than Facebook and Linkedin.
+So larger than X but less than Facebook and LinkedIn.
* You can add tags to other users.
* You can only add links in your bio so not in posts.
But you can feature links using Linktree.
From edae2a716703bbd422b725c8b44ac6a31b872fe5 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:21 +0000
Subject: [PATCH 033/142] Update source file social-media-twitter-multiple.md
---
.../social-media-twitter-multiple.md | 19 ++++++++++---------
1 file changed, 10 insertions(+), 9 deletions(-)
diff --git a/book/website/communication/social-media/social-media-twitter-multiple.md b/book/website/communication/social-media/social-media-twitter-multiple.md
index d90544e5566..139fd52ce26 100644
--- a/book/website/communication/social-media/social-media-twitter-multiple.md
+++ b/book/website/communication/social-media/social-media-twitter-multiple.md
@@ -1,12 +1,12 @@
(cm-social-media-twitter)=
-# Managing Multiple Twitter Accounts
+# Managing Multiple X Accounts
-Managing multiple accounts on Twitter can be challenging and you might be following a certain social media policy or approach that is different from how you would tweet from your personal account.
+Managing multiple accounts on X (formerly Twitter) can be challenging and you might be following a certain social media policy or approach that is different from how you would tweet from your personal account.
-Many projects and organisations have their own Twitter account that is used for advertising their research outputs and events.
+Many projects and organisations have their own X account that is used for advertising their research outputs and events.
(cm-social-media-twitter-organisation)=
-## Managing an Organisational Twitter Account
+## Managing an Organisational X Account
**1. Be sure that you are clear about what the purpose of the account is and the type of tweets that the organisation wants.**
@@ -15,9 +15,10 @@ Many projects and organisations have their own Twitter account that is used for
**2. Use scheduling to time your tweets**
-* This can be done through the Twitter web browser or by using a Twitter app such as Tweetdeck.
-* Tweetdeck is the only app owned by Twitter and it is free to use.
-But there are [other apps for all different platforms](https://www.reviewgeek.com/52119/the-best-twitter-apps-for-every-platform/), although you often have to pay for their services.
+* This can be done through the X web browser or by using an X app such as X Pro (formerly Tweetdeck).
+* X Pro is the only app owned by X.
+It was previously free to use but now requires a paid X Premium subscription.
+But there are [other apps for all different platforms](https://www.reviewgeek.com/52119/the-best-twitter-apps-for-every-platform/), although you often have to pay for their services too.
* There are other apps, such as [Buffer](https://buffer.com/), that you can use to control multiple social media channels.
* Scheduling tweets is particularly helpful if you are running an event as you can schedule tweets well in advance to give important information.
@@ -25,12 +26,12 @@ But there are [other apps for all different platforms](https://www.reviewgeek.co
* When you are responsible for multiple tweeter accounts, there is the possibility of miss tweeting.
This is when you tweet out, for example, a personal tweet using an organisational account.
-* Tweetdeck has a feature that allows you to add a confirmation step to perform an extra check before tweeting.
+* X Pro has a feature that allows you to add a confirmation step to perform an extra check before tweeting.
This helps to prevent this issue.
**4. Enabling multiple users of the same account**
-* Also on Tweetdeck, you can [set up an account as a team to allow multiple users to have different access](https://help.twitter.com/en/using-twitter/tweetdeck-teams).
+* Also on X Pro, you can [set up an account as a team to allow multiple users to have different access](https://help.twitter.com/en/using-x/postdeck-teams).
* There will be one person that is the admin for the account and then the other users are contributors.
* As a contributor you can post Tweets, Direct Message, like, and Retweet for the team account.
You cannot change the password or manage account settings.
From 42a3ff82f65373825658fd957a165d4efb012515 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:21 +0000
Subject: [PATCH 034/142] Update source file social-media-twitter-tips.md
---
.../social-media/social-media-twitter-tips.md | 46 +++++++++----------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/book/website/communication/social-media/social-media-twitter-tips.md b/book/website/communication/social-media/social-media-twitter-tips.md
index e14035d8a39..2fe993e99d9 100644
--- a/book/website/communication/social-media/social-media-twitter-tips.md
+++ b/book/website/communication/social-media/social-media-twitter-tips.md
@@ -1,20 +1,19 @@
(cm-social-media-twitter-tips)=
-# Tips for Starting with Twitter
+# Tips for Starting with X
-Twitter has 353 million monthly active users.
-You are limited to 280 characters and the style is more informal and chatty than other platforms like Linkedin.
-You can use links, photos (1200 x 628 pixels) and videos (max 2 minutes 20 secs) in similar ways to the other social media platforms.
+On X (formerly Twitter) you are limited to 280 characters unless you pay for X Premium. The style tends to be more informal and chatty than other platforms like Linkedin.
+You can use links, photos and videos (max 2 minutes 20 secs) in similar ways to the other social media platforms.
-Below are general tips for starting to use Twitter for personal academic purposes. Some of the tips have been adapted from 'Practical tips for scientists using twitter' {cite:ps}`Chabrol2021twitter`.
+Below are general tips for starting to use X for personal academic purposes. Some of the tips have been adapted from 'Practical tips for scientists using twitter' {cite:ps}`Chabrol2021twitter`.
-But when starting with Twitter it is important to first consider what your purpose for using it is.
-This will help you develop your voice (how you want to be heard, what topics you focus on, your overall message) on Twitter.
+But when starting with X it is important to first consider what your purpose for using it is.
+This will help you develop your voice (how you want to be heard, what topics you focus on, your overall message) on X.
-**1. Choose a good Twitter handle and write a good bio**
+**1. Choose a good X handle and write a good bio**
* Add a photo, cover image and short bio that is relevant to the research you are doing.
* Your bio can be linked to accounts such as your institution using their @, your funding body and common hashtags for your subject.
-* You might want to have a specific Twitter account for your project or organisation as well as a personal one.
+* You might want to have a specific X account for your project or organisation as well as a personal one.
**2. Make lists**
@@ -28,21 +27,22 @@ Therefore, think carefully about the language you use, avoid jargon and subject-
**4. Add subject-specific hashtags**
-* You only have 280 characters so using hashtags to link to different groups of interest is an important way to get your message out there.
+* Unless you're paying for X Premium you'll only have 280 characters, so using hashtags to link to different groups of interest is an important way to get your message out there.
* Tweets with hashtags can increase engagement by almost 100% for individuals.
* There are also regular hashtags for each day of the week, for example, #MondayMotivation or #FridayFeeling.
**5. Include some other accounts in your tweet**
* Linking your tweet to other accounts using @ will mean you get more retweets and therefore will spread your tweet further.
-* It is a good idea to find other researchers and organisation that have large Twitter followings.
+* It is a good idea to find other researchers and organisations that have large X followings.
This gives your tweet the largest reach possible.
**6. Add visuals**
* You can use images and gifs to draw attention to your tweets.
* If you don't have an image, a link will generate an image so make sure that the link is up to date and has a relevant image for your tweet.
-* Yow also have the option to add a description of the image so that content is accessible to more people. Here is a link to the twitter help page on [how to make images accessible for people](https://help.twitter.com/en/using-twitter/picture-descriptions).
+* You also have the option to add a description of the image so that content is accessible to more people.
+Here is a link to the X help page on [how to make images accessible for people](https://help.twitter.com/en/using-x/picture-descriptions).
**7. Don't start a tweet with '@'**
@@ -55,39 +55,39 @@ This gives your tweet the largest reach possible.
**9. Take care of yourself**
-* Not all the interactions that you have on Twitter will be pleasant as some people find fun in starting arguments or being offensive towards you.
+* Not all the interactions that you have on X will be pleasant as some people find fun in starting arguments or being offensive towards you.
* It is best not to interact with these people.
* You can follow [Charles' Rules of Arguments](https://geekfeminism.wikia.org/wiki/Charles%27_Rules_of_Argument).
This sets out that if you receive an argumentative reply, you should state your position once explaining any misunderstandings and then do not reply again.
Let others come to your defence.
* If it continues, you can block this person and report the abuse.
-* Here is a link to the Twitter help page about [how to block accounts](https://help.twitter.com/en/using-twitter/blocking-and-unblocking-accounts).
+* Here is a link to the X help page about [how to block accounts](https://help.twitter.com/en/using-x/blocking-and-unblocking-accounts).
-Starting to use Twitter might involve tweeting about new papers and useful resources in your field, events that you go to such as workshops and conferences, and retweeting other people in your field to highlight their work.
+Starting to use X might involve tweeting about new papers and useful resources in your field, events that you go to such as workshops and conferences, and retweeting other people in your field to highlight their work.
You might also want to start with a series of intro tweets to introduce yourself, your career so far and your current work.
You can pin this to your profile so that it is always what people see first.
-## Twitter Terms
+## X terms
These terms are adapted from {cite:ps}`Cheplygina2020twitter`.
-* Confirmation step - Enabling a checking process tweets before posting using Tweetdeck.
+* Confirmation step — Enabling a checking process tweets before posting using X Pro (formerly Tweetdeck).
* Direct message (DM) — A private message that is only visible to the sender and the specifically identified recipients.
-By default, regular Twitter messages are visible to the whole world, including (via search engines such as Google) people who do not have a Twitter account.
+By default, regular messages on X are visible to the whole world, including (via search engines such as Google) people who do not have an account on X.
* Hashtag (#) — Used to make it easier to find tweets with a common theme by defining keywords, for example, tweets about an event (#BookDash) or career talks (#PhDChat).
-* Hat Tip or Heard Through (HT) - Used for thanking the source of a tweet.
-* Like (♡) - Used for showing you like a tweet—a fast way to give feedback without replying.
+* Hat Tip or Heard Through (HT) — Used for thanking the source of a tweet.
+* Like (♡) — Used for showing you like a tweet—a fast way to give feedback without replying.
* There is no similar function for disliking a tweet.
-* List — A list of Twitter users that can be public (followed by anyone) or private.
+* List — A list of X users that can be public (followed by anyone) or private.
* Lists can be used to follow accounts that tweet about specific topics, but which you don’t want to follow yourself.
* Live-tweeting — Tweeting short summaries of an event, for example of a conference talk, as it is happening.
* Mentioning (@) — If you mention someone with their account handle (“This paper by @CaAl is great”), your tweet will show up in their notifications.
* Notifications — Tweets that mention you and replies, retweets and likes for your tweets.
* Quote-tweet — Sharing a tweet by someone else in a quote, while adding your comments.
-* Retweet (RT)— Sharing a tweet that was originally made by someone else.
+* Retweet (RT) — Sharing a tweet that was originally made by someone else.
* Subtweeting — Tweeting about somebody without explicitly mentioning their handle, so that they are not informed of your comment.
* Thread — A series of tweets on one subject, for instance, ten tweets about a new research paper.
* Timeline — The tweets from the people you follow.
-* Tweetdeck - App that can be used to tweet and run multiple accounts.
+* X Pro — App formerly called Tweetdeck available to paid subscribers that can be used to tweet and run multiple accounts.
From b53e30df2bff09ca2de85ee261702e2e230f150a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:22 +0000
Subject: [PATCH 035/142] Update source file acknowledgement.md
---
book/website/community-handbook/acknowledgement.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/community-handbook/acknowledgement.md b/book/website/community-handbook/acknowledgement.md
index 569d47132c3..cd225e35651 100644
--- a/book/website/community-handbook/acknowledgement.md
+++ b/book/website/community-handbook/acknowledgement.md
@@ -23,5 +23,5 @@ Furthermore, we invite every community member to update the {ref}`Record of Cont
In this chapter, we provide details on the following aspects:
- who our contributors and community members are
- how we create opportunities for a shared ownership of this project
-- how we can use record of contributions to highlight work of our community members
-- what the different types and possible pathways for contributions exist in _The Turing Way_
+- how we can use the record of contributions to highlight the work of our community members
+- what different types and possible pathways for contributions exist in _The Turing Way_
From 3f873ae46e624331bcd0d480b45e69a29ab9af1e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:23 +0000
Subject: [PATCH 036/142] Update source file acknowledgement-examples.md
---
.../acknowledgement-examples.md | 102 +++++++++---------
1 file changed, 51 insertions(+), 51 deletions(-)
diff --git a/book/website/community-handbook/acknowledgement/acknowledgement-examples.md b/book/website/community-handbook/acknowledgement/acknowledgement-examples.md
index c1a5bf0534a..d2a90350c1d 100644
--- a/book/website/community-handbook/acknowledgement/acknowledgement-examples.md
+++ b/book/website/community-handbook/acknowledgement/acknowledgement-examples.md
@@ -4,51 +4,51 @@
In the previous subchapters, we discussed how we acknowledge our contributors for their work in _The Turing Way_.
We also describe the [Contributors section](https://github.com/the-turing-way/the-turing-way#contributors) of the [`README`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) file and the [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) file as {ref}`Record of Contributions`, which are updated regularly to reflect the contribution types and personal highlights of the contributors.
-In this subchapter, we will explore the different types of contributions that exist within _The Turing Way_, and describe those with the help of {ref}`personas and pathways` our contributors may take to make their contributions.
+In this subchapter, we will explore the different types of contributions that exist within _The Turing Way_, and describe those with the help of the {ref}`personas and pathways` our contributors may take to make their contributions.
Furthermore, we describe how each persona will be acknowledged in _The Turing Way_.
## Bug fixing
-We use the term "bug" for small errors in the text or code like typos formatting issues or broken links, or minor fixes.
+We use the term "bug" for small errors in the text or code like typos, formatting issues or broken links, or minor fixes.
- *Persona for Small bug fixing*: Fraya found a typo and fixed it.
- **Acknowledgement:** They are acknowledged in the Contributors table with a 🐛 (`bug`) emoji.
- *Persona for fixing bug while maintaining sustained engagement*: Amal has found multiple typos on multiple visits to the project and contributes to conversations in issues about where these typos cause confusion or need additional input to fix.
Amal has had a sustained engagement with the community.
- - **Acknowledgement:** Amal is acknowledged in the Contributors table with a 🐛 (`bug`) and a 🤔 (`idea`) emoji and named as an author on the last 2 releases of the book.
+ - **Acknowledgement:** Amal is acknowledged in the Contributors table with a 🐛 (`bug`) and an 🤔 (`idea`) emoji and named as an author on the last 2 releases of the book.
## Providing examples
-Contributors can also provide examples that can make _The Turing Way_ chapters comprehensible for the readers.
+Contributors can also provide examples that can make _The Turing Way_ chapters comprehensible for readers.
- *Persona for adding examples*: Divna made a pull request to add an example that enhanced the quality of the chapter.
- - **Acknowledgement:** Divna is acknowledged with 💡(`example`) emoji in the Contributors table.
+ - **Acknowledgement:** Divna is acknowledged with an 💡 (`example`) emoji in the Contributors table.
- *Persona for adding examples*: Pawel wrote a subchapter and added it through a pull request to add a detailed example that demonstrated the content of the chapter being used in a real world example.
- - **Acknowledgement:** Pawel is acknowledged with 💡(`example`) emoji in the Contributors table and named as an author on the last 3 releases of the book.
+ - **Acknowledgement:** Pawel is acknowledged with an 💡 (`example`) emoji in the Contributors table and named as an author on the last 3 releases of the book.
## Code and scripts
We encourage our contributors to write a piece of code, bots or scripts to help improve the project workflow.
- *Persona for writing scripts for the project*: Kendra wrote a Python script to spot a Latin word in a new contribution, which should be avoided in this book.
- - **Acknowledgement:** Kendra is acknowledged with 💻 (`code`) emoji in the Contributors table.
+ - **Acknowledgement:** Kendra is acknowledged with a 💻 (`code`) emoji in the Contributors table.
- *Persona for reusing an existing tool*: Serena set up the continuous integration pipeline for the book using GitHub action features.
They further wrote a Python script to make the error report easy to understand and fix.
- - **Acknowledgement:** Serena is acknowledged with 💻 (`code`) emoji in the Contributors table along with the 🚧 (`maintenance`) emoji and named as an author in the most recent release of the book.
+ - **Acknowledgement:** Serena is acknowledged with a 💻 (`code`) emoji in the Contributors table along with the 🚧 (`maintenance`) emoji and named as an author in the most recent release of the book.
## Dataset
Contributors can provide test data for a test or to link with a chapter to improve the overall content.
- *Persona for reusing a self-generated dataset*: Yan created a small dataset to link to the version control chapter to demonstrate how to version control data.
- - **Acknowledgement:** Yan is acknowledged with 🔣 (`data`) emoji in the Contributors table.
-- *Persona for creating a data set for the project*: Xenia added a data set in the research compendia chapter and wrote a section to explain how to create a compendia for the research data using the example date set.
- - **Acknowledgement:** Xenia is acknowledged with 🔣 (`data`) emoji in the Contributors table along with 🖋 (`content`) emoji for writing a chapter.
+ - **Acknowledgement:** Yan is acknowledged with a 🔣 (`data`) emoji in the Contributors table.
+- *Persona for creating a data set for the project*: Xenia added a data set in the research compendia chapter and wrote a section to explain how to create a compendia for the research data using the example data set.
+ - **Acknowledgement:** Xenia is acknowledged with a 🔣 (`data`) emoji in the Contributors table along with a 🖋 (`content`) emoji for writing a chapter.
They are named as an author in the most recent version of the book.
## Reviewing chapters and other pull requests
-Review process of a newly contributed chapter or a subsection of an existing chapter involves approving the language and structure of a chapter or a section of a chapter, flagging errors or typos, asking for clarifications if certain parts of the content or statements are unclear, suggesting modifications and improving the overall quality of someone's contribution.
+The review process of a newly contributed chapter or a subsection of an existing chapter involves approving the language and structure of a chapter or a section of a chapter, flagging errors or typos, asking for clarifications if certain parts of the content or statements are unclear, suggesting modifications and improving the overall quality of someone's contribution.
- *Persona for reviewing one pull request*: Tashan has reviewed a pull request that contributed one additional paragraph to an already existing chapter.
They approved the pull request after catching two typos and giving a suggestion for a clearer phrasing of one sentence.
@@ -56,7 +56,7 @@ They approved the pull request after catching two typos and giving a suggestion
- *Persona for reviewing pull request over sustained engagement*: Sadaf has reviewed a new chapter on "Secure communication for distributed teams".
She gave comprehensive feedback on the structure of the proposed references and suggested a new format.
She was engaged for multiple reviews of the same pull request and engaged closely with the community member who wrote the chapter.
- - **Acknowledgement:** Sadaf is acknowledged in the Contributors table with the 👀 (`review`) and 🤔 (`idea`) emojis, and she is named as an author on the last release of the book.
+ - **Acknowledgement:** Sadaf is acknowledged in the Contributors table with the 👀 (`review`) and 🤔 (`idea`) emojis, and she is named as an author on the latest release of the book.
## Chapter contribution
@@ -65,45 +65,45 @@ The various contributions to a chapter are made towards designing, writing, and
- *Persona for writing a chapter*: Jordon has written a chapter on "Setting expectations across academia and industry".
He started writing the chapter at a Turing Way Book Dash event, based on an idea they had developed in advance of the event.
He responded to review comments and iteratively improved the chapter until the pull request was merged.
- - **Acknowledgement:** He is acknowledged in the Contributors table with a 👀 (`review`), 🤔 (`idea`) and 🖋 (`content`) emoji.
- He is also named as an author on the last release of the book.
+ - **Acknowledgement:** He is acknowledged in the Contributors table with 👀 (`review`), 🤔 (`idea`) and 🖋 (`content`) emojis.
+ He is also named as an author on the latest release of the book.
- *Persona for reviewing and making chapter contribution*: Sia recently learned about _The Turing Way_ project and started contributing by reviewing a pull request for the chapter "Setting expectations across academia and industry".
She offered some critical suggestions and engaged in helpful discussions with the author to help them improve their contribution.
She ended up writing a new section of that chapter as well.
- - **Acknowledgement:** She is acknowledged in the Contributors table with 👀 (`review`), 🤔 (`idea`) and 🖋 (`content`) emoji and is named as an author in the last release of the book.
+ - **Acknowledgement:** She is acknowledged in the Contributors table with 👀 (`review`), 🤔 (`idea`) and 🖋 (`content`) emojis and is named as an author in the latest release of the book.
- *Persona for designing a chapter*: At the event, Ishan collaborated with Mafalda in brainstorming a chapter together and created an issue on that.
After the event, Ishan did not have time to contribute to the chapter anymore as an author or contributor.
- **Acknowledgement:** Ishan is acknowledged in the Contributors table with the 🤔 (`idea`) emoji.
- *Persona for designing and writing a chapter*: After the same event as above, Mafalda completed the chapter that she brainstormed with Ishan.
- She submitted her contribution as a pull request to the Turing Way and responded to the review comments.
- - **Acknowledgement:** She is acknowledged in the Contributors table with 🤔 (`idea`) and 🖋 (`content`) emoji and is named as an author in the last release of the book.
+ She submitted her contribution as a pull request to _The Turing Way_ and responded to the review comments.
+ - **Acknowledgement:** She is acknowledged in the Contributors table with 🤔 (`idea`) and 🖋 (`content`) emojis and is named as an author in the latest release of the book.
## Accessibility
Contributors reporting or working on accessibility issues.
- *Persona for technical improvement for accessibility*: Endre wrote a script to make sure that _The Turing Way_ book is properly readable for low vision readers.
- - **Acknowledgement:** He is acknowledged with ♿️ (`ally`) emoji in the Contributors Table along with 💻 (`code`) emoji and named as an author in the last 3 releases of the book.
+ - **Acknowledgement:** He is acknowledged with an ♿️ (`ally`) emoji in the Contributors Table along with a 💻 (`code`) emoji and named as an author in the last 3 releases of the book.
- *Persona for writing accessibility related resources*: Rajmund wrote chapters on the community participation in the Community Handbook that discusses the accessibility aspects of working in a research team.
- - **Acknowledgement:** He is acknowledged with ♿️ (`ally`) emoji in the Contributors Table, along with 🖋 (`content`) emoji for writing and named as an author in the last 2 releases of the book.
+ - **Acknowledgement:** He is acknowledged with an ♿️ (`ally`) emoji in the Contributors Table, along with a 🖋 (`content`) emoji for writing and named as an author in the last 2 releases of the book.
- *Persona for enhancing the accessibility aspects of the resources*: Sammy reviewed a few chapters in _The Turing Way_ to remove the gendered language.
They also wrote a subchapter in the community handbook's chapter on a style guide to help others follow a guideline to avoid gendered language from future contributions.
- - **Acknowledgement:** They are acknowledged with ♿️ (`ally`) emoji in the Contributors Table along with 🖋 (`content`) emoji for chapter contributions and named as an author in the last 2 releases of the book.
+ - **Acknowledgement:** They are acknowledged with an ♿️ (`ally`) emoji in the Contributors Table along with a 🖋 (`content`) emoji for chapter contributions and named as an author in the last 2 releases of the book.
## Translation
-Translation process in _The Turing Way_ includes aspects translating _The Turing Way_ chapters into languages other than English and reviewing them.
-The translation infrastructure as of May 2020 is [Trasifex](https://www.transifex.com/theturingway/theturingway/dashboard/).
+The translation process in _The Turing Way_ includes aspects translating _The Turing Way_ chapters into languages other than English and reviewing them.
+The translation infrastructure as of May 2020 is [Transifex](https://www.transifex.com/theturingway/theturingway/dashboard/).
- *Persona for translating resources*: Anika has translated 3 paragraphs of the version control chapter into Swedish following the standard process defined in _The Turing Way_ repository.
- **Acknowledgement:** She is acknowledged in the Contributors table with the 🌍 (`translation`) emoji.
- *Persona for translating and improving resources*: Jamil has translated the version control chapter into Arabic following the standard process defined in The Turing Way repository and adapted the chapter to make it more logical to read in Arabic.
- - **Acknowledgement:** He is acknowledged in the Contributors table with the 🌍 (`translation`) emoji and 🖋 (`content`), and named as an author on the last release of the book.
+ - **Acknowledgement:** He is acknowledged in the Contributors table with the 🌍 (`translation`) and 🖋 (`content`) emojis, and named as an author on the latest release of the book.
- *Persona for translating resources and mentoring others*: Anabel has written a general guideline for translation and translated the introduction chapter into Turkish.
- - **Acknowledgement:** Anabel is acknowledged with 🌍 (`translation`), 🤔 and 🖋 (`content`) emoji, and named as an author on the last release of the book.
-- *Persona for translating resources, mentoring others and maintaining an infrastructure*: Anthony has set up the infrastructure and process for managing translation of The Turing Way into multiple languages.
- They have translated 3 chapters into Chinese and worked closely with the core team to get mentored contributions by other members in multiple languages.
- - **Acknowledgement:** They are acknowledged with 🌍 (`translation`), 🤔 (`idea`), 🚇(`infra`) and 🚧 (`maintenance`) emoji, and named as an author on the last release of the book.
+ - **Acknowledgement:** Anabel is acknowledged with 🌍 (`translation`), 🤔 and 🖋 (`content`) emojis, and named as an author on the latest release of the book.
+- *Persona for translating resources, mentoring others and maintaining an infrastructure*: Anthony has set up the infrastructure and process for managing translation of _The Turing Way_ into multiple languages.
+ They have translated 3 chapters into Chinese and worked closely with the core team to get mentored contributions from other members in multiple languages.
+ - **Acknowledgement:** They are acknowledged with 🌍 (`translation`), 🤔 (`idea`), 🚇(`infra`) and 🚧 (`maintenance`) emojis, and named as an author on the latest release of the book.
## Organisational support
@@ -117,65 +117,65 @@ These efforts are highly encouraged to ensure the sustainability of their resour
- **Acknowledgement:** The NNAII is acknowledged as a "Collaborating organisation" in the {ref}`the record of contributions` with detailed contributions from each of their members involved in this project.
- *Persona for a contributing member from the organisation*: Abby is one of the members of the NNAII who contributed to the guidance before she left to join a non-profit last year.
After leaving NNAII, Abby has designed and written a new chapter in her own time.
- - **Acknowledgement:** In addition to her previous acknowledgments, she will be acknowledged with a 🖋 (`content`) and 🤔 (`idea`) emoji in the Contributors Table and her {ref}`the record of contributions` will develop independently of the NNAII.
+ - **Acknowledgement:** In addition to her previous acknowledgments, she will be acknowledged with a 🖋 (`content`) and 🤔 (`idea`) emoji in the Contributors Table and her {ref}`record of contributions` will develop independently of the NNAII.
- *Persona for the supporting (indirect contributor) members from the organisation*: Kadie is a programme director at the NNAII who manages the team that wrote the guidance that has been incorporated into _The Turing Way_.
- **Acknowledgement:** She is acknowledged in the Contributors table with the 💵 (`finance`) emoji.
Kadie was asked if she would like to be an author on the most recent release of _The Turing Way_ book but declined as she did not personally feel that she had contributed enough to be named as an author.
- *Persona for a contributing member from the organisation with sustained engagement*: Patty works in a National Library and her employers have approved her to host their resources as chapters in _The Turing Way_.
Patty has developed materials, contributed to the community discussions and reviewed others' pull requests on the GitHub repository.
- - **Acknowledgement:** Patty will be listed in the Contributors Table with a 🤔 (`idea`), 🖋 (`content`) and 👀 (`review`) emoji and named as an author on the last release of the book..
+ - **Acknowledgement:** Patty will be listed in the Contributors Table with 🤔 (`idea`), 🖋 (`content`) and 👀 (`review`) emojis and named as an author on the latest release of the book..
## Maintenance
-Maintenance work in _The Turing Way_ applies to the multiple aspects, some of which are: responding to the questions in community spaces such as Gitter, GitHub issues, or Twitter; the technical infrastructure of the GitHub repository, associated GitHub bots, scripts and continuous integration pipeline; online hosting platforms of Jupyter book and Netlify; and translation infrastructure of Transifex.
+Maintenance work in _The Turing Way_ applies to multiple aspects, some of which are: responding to the questions in community spaces such as Gitter, GitHub issues, or X (formerly Twitter); the technical infrastructure of the GitHub repository, associated GitHub bots, scripts and continuous integration pipeline; the online hosting platforms of Jupyter book and Netlify; and the translation infrastructure of Transifex.
- *Persona for maintaining community interactions*: Neve has helped two contributors on two individual occasions by responding to a question on the Turing Way Gitter channel and a question on one of the issues in _The Turing Way_ GitHub repository.
- - **Acknowledgement:** He is acknowledged in the Contributors table with the 💬 (`question`) and 🤔 (`idea`) emoji.
+ - **Acknowledgement:** He is acknowledged in the Contributors table with the 💬 (`question`) and 🤔 (`idea`) emojis.
- *Persona for maintaining community interactions with sustained engagement*: Ursula regularly points new contributors to documentation and submits pull requests to improve the guidance when she sees unclear areas.
She reviews pull requests from others working to make the process of contributing smoother.
- - **Acknowledgement:** She is acknowledged in the Contributors table with the 💬 (`question`), 🤔 (`idea`), 👀 (`review`) and 🚧 (`maintenance`) emoji , and named as an author on the last two releases of the book.
+ - **Acknowledgement:** She is acknowledged in the Contributors table with the 💬 (`question`), 🤔 (`idea`), 👀 (`review`) and 🚧 (`maintenance`) emojis, and named as an author on the last two releases of the book.
- *Persona for maintaining project infrastructure*: Gaia is maintaining the back-end infrastructure of the Jupyter Book and supports the continuous integration aspect of the project repository by replying to related issues and providing solutions to fix them.
- - **Acknowledgement:** She is acknowledged in the Contributors table with 🚇 (`infra`) and 🚧 (`maintenance`) emoji, and named as an author on the last release of the book.
-- *Persona for maintaining project infrastructure and mentoring other*: Jamil has set up the infrastructure and process for managing translation of _The Turing Way_ into multiple languages.
+ - **Acknowledgement:** She is acknowledged in the Contributors table with 🚇 (`infra`) and 🚧 (`maintenance`) emojis, and named as an author on the latest release of the book.
+- *Persona for maintaining project infrastructure and mentoring others*: Jamil has set up the infrastructure and process for managing translation of _The Turing Way_ into multiple languages.
They support new translators by answering their questions related to the translation process.
- - **Acknowledgement:** They are acknowledged with 🤔 (`idea`), 🚇 (`infra`) and 🚧 (`maintenance`) emoji, and named as an author on the last release of the book.
+ - **Acknowledgement:** They are acknowledged with 🤔 (`idea`), 🚇 (`infra`) and 🚧 (`maintenance`) emojis, and named as an author on the latest release of the book.
## Representing the Turing Way
-Anyone who shares _The Turing Way_ resources in any relevant publication, learning material, conference presentations or community event are acknowledged for representing _The Turing Way_.
+Anyone who shares _The Turing Way_ resources in any relevant publication, learning material, conference presentations or community event is acknowledged for representing _The Turing Way_.
These members may or may not have previously contributed to the project.
They either volunteer or are recommended by _The Turing Way_ team members for representing this community within or outside the project.
- *Persona for highlighting project resources*: Yehuda used one of the Scriberia and _The Turing Way_ illustrations in a recent talk they gave at an open source workshop that was hosted by their company.
- They included links to _The Turing Way_ book, GitHub repository and Twitter handle.
+ They included links to _The Turing Way_ book, GitHub repository and X handle.
Their slides are available under a CC-BY license and are requested to be linked in a monthly newsletter.
- **Acknowledgement:** They are acknowledged in the Contributors table with the 🔊 (`Talk`) emoji.
- *Persona for giving a talk on _The Turing Way_*: Noah is a long time contributor to _The Turing Way_, they answer questions and review pull requests regularly.
In March 2020, Kirstie - lead developer of _The Turing Way_ - recommended Noah as a suggested speaker to give a talk about the Project Design section of _The Turing Way_ at a conference on open source community management.
She worked with Noah to practice his presentation in advance of the talk.
Noah's slides are available under a CC-BY license and are linked from a page in the community handbook.
- - **Acknowledgement:** They are acknowledged in the Contributors table with the 🔊 (`Talk`), 🚧 , 👀 (`review`), 🤔 (`idea`) and 💬 (`question`) emoji and named as an author on the last release of the book.
+ - **Acknowledgement:** They are acknowledged in the Contributors table with the 🔊 (`Talk`), 🚧 (`maintenance`), 👀 (`review`), 🤔 (`idea`) and 💬 (`question`) emojis and named as an author on the last release of the book.
## Training, workshops or community events
Members can help in organising a training session, host a workshop delivered by the team members, or help in delivering a community event.
1. Klara **delivered a training** session on Binder co-organized by _The Turing Way_ core team members.
-2. Petra **help organising** a 2-hour long workshop by _The Turing Way_ at a PhD conference and helped deliver it by managing contributions on the GitHub repository.
-3. Uri previously attended a bookdash event as a selected participant and joined the most recent bookdash as a **helper to support new attendees**.
+2. Petra **helped organising** a 2-hour long workshop by _The Turing Way_ at a PhD conference and helped deliver it by managing contributions on the GitHub repository.
+3. Uri previously attended a book dash event as a selected participant and joined the most recent book dash as a **helper to support new attendees**.
4. Paolo **hosted a Collaboration Cafe** in a time zone compatible with the contributors from New Zealand.
-**Acknowledgement:** All these contributors will be acknowledged with 📋 (`eventOrganizing`) emoji in the Contributors Table.
+**Acknowledgement:** All these contributors will be acknowledged with the 📋 (`eventOrganizing`) emoji in the Contributors Table.
## Tutorial and training material
We invite our members to create tutorials or share their training materials that can be supplemented with the existing chapters in _The Turing Way_.
- *Persona for creating training materials in the project*: Aune added multiple-choice questions (as a tool for formative assessment) at the end of 3 different chapters to help readers evaluate their understanding of the concepts described in those chapters.
- - **Acknowledgement:** She is acknowledged with ✅ (`tutorial`) emoji in the Contributors table.
+ - **Acknowledgement:** She is acknowledged with the ✅ (`tutorial`) emoji in the Contributors table.
- *Persona for reusing a training material in the project*: Leo had developed training material on machine learning for a workshop they organised in the past for their colleagues.
They have added this material with a new chapter they authored in the book for reproducibility in _The Turing Way_.
- - **Acknowledgement:** They are acknowledged with ✅ (`tutorial`) emoji in the Contributors table along with 🖋 (`content`) emoji and named as an author on the last release of the book.
+ - **Acknowledgement:** They are acknowledged with the ✅ (`tutorial`) emoji in the Contributors table along with the 🖋 (`content`) emoji and named as an author on the latest release of the book.
## Blog posts and articles
@@ -184,31 +184,31 @@ Contributors writing about _The Turing Way_ in articles, blogs, or other online
1. Khasan wrote a relevant online **blogpost that was highlighted** in the monthly newsletter.
2. Eva wrote a research article and **cited a chapter from _The Turing Way_**, which was then added to the _The Turing Way_ bibliography.
-**Acknowledgement:** These contributors are acknowledged with 📝 (`blog`) emoji in the Contributors Table.
+**Acknowledgement:** These contributors are acknowledged with the 📝 (`blog`) emoji in the Contributors Table.
## Videos and recordings
-We encourage creating video content or animations, record online interactive discussions or link any relevant videos our contributors may have created in the past that can be used as a learning tool and enhance the quality of _The Turing Way_ content.
+We encourage creating video content or animations, recording online interactive discussions or linking any relevant videos our contributors may have created in the past that can be used as a learning tool and enhance the quality of _The Turing Way_ content.
- *Persona for helping record and edit videos for the project*: Jakaria hosted a collaboration cafe, recorded the session, edited to be uploaded on _The Turing Way_ YouTube channel.
- - **Acknowledgement:** Jakaria is acknowledged with 📹 (`video`) emoji in the Contributors table along with 📋 (`eventOrganizing`) emoji for event organisation.
+ - **Acknowledgement:** Jakaria is acknowledged with the 📹 (`video`) emoji in the Contributors table along with the 📋 (`eventOrganizing`) emoji for event organisation.
- *Persona for creating training videos*: Rene created 3 short videos to guide step by step learning of git-based version control and linked them to an existing chapter on git and GitHub.
- - **Acknowledgement:** Rene is acknowledged with 📹 (`video`) emoji in the Contributors table and named as an author on the last release of the book.
+ - **Acknowledgement:** Rene is acknowledged with the 📹 (`video`) emoji in the Contributors table and named as an author on the latest release of the book.
## Financial support
Researchers and support staff from a collaborating organisation can help with searching for funding, help with writing a grant proposal or providing financial support directly or indirectly for the development of the project.
- *Persona for managing funding*: Laura is managing the sponsorship offered to _The Turing Way_ through one of its collaborating organisation.
- - **Acknowledgement:** Laura is acknowledged with 💵 (`financial`) emoji in the Contributors table.
+ - **Acknowledgement:** Laura is acknowledged with the 💵 (`financial`) emoji in the Contributors table.
- *Persona for helping gain funding*: Ismael shared a funding opportunity with an intention to financially support the development of the guide on ethical research.
They also helped in editing a grant proposal.
- - **Acknowledgement:** Ismael is acknowledged with 🔍 (`fundingFinding`) emoji in the Contributors table and 💵 (`financial`) emoji for their support and work and named as an author on the last release of the book.
+ - **Acknowledgement:** Ismael is acknowledged with the 🔍 (`fundingFinding`) emoji in the Contributors table and the 💵 (`financial`) emoji for their support and work and named as an author on the latest release of the book.
## Project Management
Team members, core contributors and community members with sustained engagements often take on project management tasks and support _The Turing Way_ community and project as a whole.
-**Acknowledgement:** These members are acknowledged with 📆 (`ProjectManagement`) emoji in the Contributors table.
+**Acknowledgement:** These members are acknowledged with the 📆 (`projectManagement`) emoji in the Contributors table.
*Did we miss listing a contribution type? Please create an issue on the GitHub repository to discuss that with the team members.*
From 086dd7c8d777f11926b3813a6eac9e63dc5626b2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:23 +0000
Subject: [PATCH 037/142] Update source file acknowledgement-members.md
---
.../acknowledgement-members.md | 23 +++++++++++++------
1 file changed, 16 insertions(+), 7 deletions(-)
diff --git a/book/website/community-handbook/acknowledgement/acknowledgement-members.md b/book/website/community-handbook/acknowledgement/acknowledgement-members.md
index 005febfb76f..c5dcb48c9bb 100644
--- a/book/website/community-handbook/acknowledgement/acknowledgement-members.md
+++ b/book/website/community-handbook/acknowledgement/acknowledgement-members.md
@@ -2,9 +2,18 @@
# Community and Shared Ownership
As a community-led project, we believe in and promote a collaborative approach to develop the content of this book.
-For example, writing _The Turing Way_ chapter is an iterative process that involves designing, outlining, writing, reviewing, and editing its contents.
+For example, writing a _The Turing Way_ chapter is an iterative process that involves designing, outlining, writing, reviewing, and editing its contents.
Similarly, community-oriented processes evolve over time with the help and feedback from the community members.
+```{figure} ../../figures/people-process.*
+---
+height: 500px
+name: people-process
+alt: Cartoon-like sketch with pink colours of a large sunflower with a star in the middle sitting on top of the ground. It has the text next to the flower that says 'valuing people and processes behind research'. Below the ground, three roots extend, each terminating with an illustrated figure symbolising the often hidden efforts in research. From left to right, a female presenter giving a talk, a mustached male figure in a lab coat collecting data, and a person with glasses diligently working on a laptop. These figures represent the unseen work integral to the research process.
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
## Community members, contributors and co-authors
Everyone who contributes to this book, no matter how small or big their contributions are, is recognised in this project as a contributor and a community member.
@@ -12,10 +21,10 @@ Everyone who contributes to this book, no matter how small or big their contribu
Their contributions may include carrying out small tasks such as reporting bugs, correcting factual errors, adding references, opening issues to discuss an idea, commenting on an ongoing discussion, exchanging ideas with other members or citing and promoting _The Turing Way_.
As discussed in the next subchapter, these contributors are highlighted in the {ref}`Contributors Table`.
-Many contributors will also make substantial contributions such as writing a subchapter, maintaining community interactions, setting up or maintaining project's infrastructure, helping others in their work and supporting their participation.
+Many contributors will also make substantial contributions such as writing a subchapter, maintaining community interactions, setting up or maintaining the project's infrastructure, helping others in their work and supporting their participation.
All the substantial contributors are also highlighted in the Contributors Table and named as co-authors [{term}`def`] on the book as a whole.
As stated in our [Governance document](https://github.com/the-turing-way/the-turing-way/blob/main/GOVERNANCE.md), "substantial contribution" is a subjective term.
-Therefore, we have tried to add much detail as possible in the next subchapters through personas, contribution types and acknowledgements of those contributions including when a contributor is named as an author.
+Therefore, we have tried to add as much detail as possible in the next subchapters through personas, contribution types and acknowledgements of those contributions including when a contributor is named as an author.
Authors are listed in alphabetical order by last name.
The first author is always **The Turing Way Community**.
@@ -27,7 +36,7 @@ If these subchapters do not contain the contribution type that you are intereste
## Creating opportunities for shared ownership
-As an open-source community, the project invites contributions from the experts and enthusiasts alike to collectively develop guidance, recommendations, and practical resources that can foster a gold-standard for reproducible research.
+As an open-source community, the project invites contributions from experts and enthusiasts alike to collectively develop guidance, recommendations, and practical resources that can foster a gold-standard for reproducible research.
_The Turing Way_ core team values and promotes a culture of collaboration.
In contrast to the traditional incentive structure in academia, which often discourages open collaboration, public engagements in project advancement and sharing data early on, we promote a collaborative working culture in _The Turing Way_.
@@ -35,7 +44,7 @@ In contrast to the traditional incentive structure in academia, which often disc
We intentionally avoid individual authorship in favor of establishing shared ownership and agency in this project.
This means that no single person or organisation owns the book or any of its chapters.
The book belongs to the community and the chapters are always considered 'work in progress' so that they can evolve over time with newer contributions.
-We encourage authors to actively involve others in reviewing their work, providing missing information and adding diverse examples, which are impossible to be written by a single person.
+We encourage authors to actively involve others in reviewing their work, providing missing information and adding diverse examples, which could not possibly be written by a single person.
We hope that such collaborative efforts lower the psychological barriers for the new contributors who can propose improvements in the book by editing, moving, and adapting its content as the book grows.
@@ -46,9 +55,9 @@ These contributions include exchanging skills, sharing research components for r
## Highlight your contributions!
-In the {ref}`next subchapter `, we have listed all the documents in this project that is considered "Record of Contributions".
+In the {ref}`next subchapter `, we have listed all the documents in this project that are considered the "Record of Contributions".
-We want our community members to take pride in the valuable work they have done this project.
+We want our community members to take pride in the valuable work they have done on this project.
We invite them to edit these documents to add details of their contributions that they want to highlight in _The Turing Way_.
We welcome your suggestions and ideas for creating more ways to acknowledge you.
From 8b16aeb4ea966b01bb79a9414268580062e078e1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:24 +0000
Subject: [PATCH 038/142] Update source file acknowledgement-record.md
---
.../acknowledgement/acknowledgement-record.md | 54 +++++++++----------
1 file changed, 27 insertions(+), 27 deletions(-)
diff --git a/book/website/community-handbook/acknowledgement/acknowledgement-record.md b/book/website/community-handbook/acknowledgement/acknowledgement-record.md
index 9f5490c2ee2..1b3cd78d3ea 100644
--- a/book/website/community-handbook/acknowledgement/acknowledgement-record.md
+++ b/book/website/community-handbook/acknowledgement/acknowledgement-record.md
@@ -1,17 +1,17 @@
(ch-acknowledgement-record)=
# Record of Contributions
-Two documents in our [GitHub repository](https://github.com/the-turing-way/the-turing-way) are used for creating a record of contributions in _The Turing Way_: Contributors Table in the [`README`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) file, and [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) file.
+Two documents in our [GitHub repository](https://github.com/the-turing-way/the-turing-way) are used for creating a record of contributions in _The Turing Way_: the Contributors Table in the [`README`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) file, and the [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) file.
This record is made available in the afterword of this book as {ref}`Contributors` and {ref}`Personal Highlights`.
These documents can be used for highlighting skills that our members have gained and shared through their involvement in _The Turing Way_.
-We invite all our members to co-create this record to capture the important work they do around answering questions, representing the project, developing and maintaining the infrastructure, and all other nurturing roles that make The Turing Way community so special.
+We invite all our members to co-create this record to capture the important work they do around answering questions, representing the project, developing and maintaining the infrastructure, and all other nurturing roles that make _The Turing Way_ community so special.
The process of developing this record is described below in detail.
## 1. Contributors Table
-The [Contributors](https://github.com/the-turing-way/the-turing-way#contributors) table in [`README`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) file is updated with every contributor's name using the [all contributors bot](https://allcontributors.org/)'s [emoji key](https://allcontributors.org/docs/en/emoji-key).
+The [Contributors](https://github.com/the-turing-way/the-turing-way#contributors) table in the [`README`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) file is updated with every contributor's name using the [all contributors bot](https://allcontributors.org/)'s [emoji key](https://allcontributors.org/docs/en/emoji-key).
No contribution is too small, and these emojis allow us to recognise and fairly acknowledging all kinds of contributions our community members make to the project.
Those contributions can include (but are not limited to) bug fixing, chapter planning, writing, editing, reviewing, idea generation, presentation, project management, and maintenance.
@@ -23,7 +23,7 @@ height: 400px
name: AllContributorsEmojiKey
alt: Table with different emojis that is used by the contributors bot
---
-[Emoji key table](https://allcontributors.org/docs/en/emoji-key) of the all contributors bot that _The Turing Way_ uses for acknowledging different contributions from the community members.
+[Emoji key table](https://allcontributors.org/docs/en/emoji-key) of the all contributors bot that _The Turing Way_ uses for acknowledging different contributions from community members.
```
## 2. Contributors file
@@ -47,10 +47,10 @@ Additionally, contributors can opt to add more information they think can help t
Specifications for all types of contributions made towards _The Turing Way_ can be added in the [contributors file](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) as personal highlights.
-These highlights can be individually decided by the contributors to record what they consider to be their significant and useful for their personal profile.
-This can be supplemented with supporting materials such links to chapters, pull request, issues, and blog posts.
+These highlights can be individually decided by the contributors to record what they consider to be their significant and useful contributions for their personal profile.
+This can be supplemented with supporting materials such as links to chapters, pull requests, issues, and blog posts.
-This record can be directly translated towards the professional development of our community members, which can be further used for enhancing their personal or professional portfolio (profile, CV, resume) (see the [`contributors.md`](https://github.com/the-turing-way/the-turing-way/edit/acknowledging-contributors/contributors.md) file).
+This record can be directly translated towards the professional development of our community members, which can be further used for enhancing their personal or professional portfolio (profile, CV, resume) (see the [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) file).
_The Turing Way_ was originally funded by a [Strategic Priority Fund](https://www.ukri.org/research/themes-and-programmes/strategic-priorities-fund/) investment to the Alan Turing Institute to support [AI For Science and Government](https://www.turing.ac.uk/research/asg).
The personal highlights are very valuable for capturing the impact that _The Turing Way_ has for its community members in terms of personal networking, professional development, skill sharing and other relevant activities, and how they have made positive impacts around transparency, reproducibility and ethical collaboration in their organisation.
@@ -66,11 +66,11 @@ As a contributor, you will be able to add as many details as useful for your rec
#### Bug fixes
-*A "bug" is a small error in the text or code like typo, formatting issue or broken links.*
+*A "bug" is a small error in the text or code like a typo, formatting issue or broken link.*
-Anyone who raises bugs, related issues or fixes them are listed as contributors in the Contributors table with 🐛 (`bug`) emoji.
+Anyone who raises bugs, related issues or fixes them are listed as contributors in the Contributors table with the 🐛 (`bug`) emoji.
-The contributor's file will be updated for the contributors with a similar statement as below after the `contributor's detail`:
+The contributors file will be updated for the contributors with a similar statement as below after the `contributor's detail`:
* Personal highlights:
> I have fixed typos and made other contributions `other details like identified sections of the book that are unclear`.
@@ -79,9 +79,9 @@ The contributor's file will be updated for the contributors with a similar state
*The review process of a newly contributed chapter or a subsection of an existing chapter involves approving the language and structure of a chapter or a section of a chapter, flagging errors or typos, asking for clarifications if certain parts of the content or statements are unclear, suggesting modifications and improving the overall quality of someone's contribution.*
-Anyone who reviews a chapter is listed as reviewers and are acknowledged with 👀 (`review`) emoji in the Contributors table.
+Anyone who reviews a chapter is listed as reviewers and are acknowledged with the 👀 (`review`) emoji in the Contributors table.
-The contributor's file will be updated for the contributors with a similar statement as below:
+The contributors file will be updated for the contributors with a similar statement as below:
* Personal highlights:
> I have reviewed the chapter `Chapter name`.
@@ -93,7 +93,7 @@ The contributor's file will be updated for the contributors with a similar state
The designing, writing, and reviewing of a chapter's content are acknowledged with 🤔 (`idea`), 🖋 (`content`) and 👀 (`review`) emojis respectively in the Contributors table.
-The contributor's file will be updated for the contributors with a similar statement as below:
+The contributors file will be updated for the contributors with a similar statement as below:
* Personal highlights:
> I have designed and written a chapter on `chapter name` and `details on reviewing and structuring new content`.
@@ -101,51 +101,51 @@ The contributor's file will be updated for the contributors with a similar state
#### Translation
*The translation process in _The Turing Way_ includes aspects translating _The Turing Way_ chapters into languages other than English and reviewing them.*
-The translation infrastructure as of May 2020 is [Trasifex](https://www.transifex.com/theturingway/theturingway/dashboard/).
+The translation infrastructure as of May 2020 is [Transifex](https://www.transifex.com/theturingway/theturingway/dashboard/).
Contributors who participate in the translation process will be acknowledged in the Contributors table with the 🌍 (`translation`) emoji.
-The contributor's file will be updated for the contributors with a similar statement as below:
+The contributors file will be updated for the contributors with a similar statement as below:
* Personal highlights:
-> I have translated part of the chapter `chapter name` into `language`. I have also `details like designed and implemented a process to translate the book into multiple languages, mentored multiple contributors within the community and has translated 3 chapters of The Turing Way into Chinese`.
+> I have translated part of the chapter `chapter name` into `language`. I have also `details like designed and implemented a process to translate the book into multiple languages, mentored multiple contributors within the community and have translated 3 chapters of The Turing Way into Chinese`.
#### Organisational support
*When members participate in _The Turing Way_ community with the in-kind support of their funders and organisation, we acknowledge each member individually and list their organisations as "Collaborating organisations".
Such organisational supports are applicable when one or multiple members from a project or community collaborate to build resources in _The Turing Way_.*
-Each organisation who supports its members to collaborate with _The Turing Way_ will be listed as "Collaborating organisations" in the contributor's file.
-Each contributor from these organisation will be acknowledged individually in the Contributors Table for their specific contributions with emoji keys reflecting specific contributions made with the organisational support.
-Their contributors will be listed under their organisation's name in the contributor's file.
+Each organisation which supports its members to collaborate with _The Turing Way_ will be listed as "Collaborating organisations" in the contributors file.
+Each contributor from these organisations will be acknowledged individually in the Contributors Table for their specific contributions with emoji keys reflecting specific contributions made with organisational support.
+Their contributors will be listed under their organisation's name in the contributors file.
-Every contribution from collaborating organisation will be updated with a similar statement as below:
+Every contribution from a collaborating organisation will be updated with a similar statement as below:
* Personal highlights:
> I have made contributions `contribution type` to the chapters `chapter name`. I have also `details on other contributions like managing a team of contributors, writing a chapter`.
#### Maintenance
-*Maintenance work in _The Turing Way_ applies to the conversations in community spaces, technical infrastructure, online hosting platforms for the book, and translation infrastructure of Transifex.*
+*Maintenance work in _The Turing Way_ applies to the conversations in community spaces, technical infrastructure, online hosting platforms for the book, and the translation infrastructure of Transifex.*
Contributors will be acknowledged in the Contributors table with the 💬
-(`question`) emoji for answering questions, 🤔 (`ideas`) emoji for discussions, 🚇 (`infra`) emoji for infrastructure support, and 🚧 (`maintenance`) for community efforts or infrastructure maintenance.
+(`question`) emoji for answering questions, the 🤔 (`ideas`) emoji for discussions, the 🚇 (`infra`) emoji for infrastructure support, and the 🚧 (`maintenance`) emoji for community efforts or infrastructure maintenance.
-The contributor's file will be updated for the contributors with a similar statement as below:
+The contributors file will be updated for the contributors with a similar statement as below:
* Personal highlights:
-> I have `details like responded to questions in the community's Gitter channel, mentored multiple contributors within the community and has reviewed pull requests to fix typos in the book, maintains the backend infrastructure of the project, provide support and solution regarding Jupyter book and continuous integration, designed and implemented a process to translate the book into multiple languages, helped multiple contributors in facilitating translation efforts`.
+> I have `details like responded to questions in the community's Gitter channel, mentored multiple contributors within the community and reviewed pull requests to fix typos in the book, maintains the backend infrastructure of the project, provides support and solutions regarding Jupyter book and continuous integration, designed and implemented a process to translate the book into multiple languages, helped multiple contributors in facilitating translation efforts`.
#### Representing the Turing Way
-*Anyone who shares _The Turing Way_ resources in any relevant publication, learning material, conference presentations, or community event are acknowledged for representing _The Turing Way_.*
+*Anyone who shares _The Turing Way_ resources in any relevant publication, learning material, conference presentation, or community event are acknowledged for representing _The Turing Way_.*
Each contributor who represents _The Turing Way_ at an event is acknowledged in the Contributors table with the 📢 (`Talk`) emoji in the Contributors Table along with other contributions as applicable.
-Their contributions will be listed in the contributor's file with a similar statement as below:
+Their contributions will be listed in the contributors file with a similar statement as below:
* Personal highlights:
> I have presented a talk at _The Turing Way_ at `event's name`.
-> I have also `details like mentored multiple contributors within the community and have given talks at and event on behalf of the community`.
+> I have also `details like mentored multiple contributors within the community and have given talks at an event on behalf of the community`.
Please read personas and pathways for different contributions in the next subchapter.
From 407214e4521e45ed46e824906cf9dc0a5e35c99e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:24 +0000
Subject: [PATCH 039/142] Update source file bookdash.md
---
book/website/community-handbook/bookdash.md | 32 ++++++++++-----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/book/website/community-handbook/bookdash.md b/book/website/community-handbook/bookdash.md
index c972341c662..f89be2f7695 100644
--- a/book/website/community-handbook/bookdash.md
+++ b/book/website/community-handbook/bookdash.md
@@ -4,11 +4,11 @@
_The Turing Way_ [Book Dash events](https://the-turing-way.netlify.app/community-handbook/bookdash.html) are a less intense version of [Book Sprints](https://en.wikipedia.org/wiki/Book_sprint), where participants collaboratively work on _The Turing Way_ book synchronously to develop new chapters and review/edit existing ones to make them more accessible, comprehensive and up-to-date.
They also contribute to enhancing the project by improving the ways we work in the community and take the lead on accomplishing different tasks or subprojects.
-In the past, we have organised 1-2 days long Book Dash events in person or in a hybrid format, where one of the participants coordinated with their team remotely.
+In the past, we have organised 1-2 day long Book Dash events in person or in a hybrid format, where one of the participants coordinated with their team remotely.
However, to ensure that international participants have an equal chance to join and address the challenges of hosting in-person events during the COVID-19 pandemic, we started hosting Book Dashes virtually.
These virtual Book Dashes are five days long, designed for flexible participation by members in different time zones.
-Meaning, rather than committing their entire working day, participants can choose one or multiple 2.5 hours short collaborative co-working calls, called "contribution sessions" each day based on their availability.
-In the future, we will co-design hybrid events with "online-first" approach for the Book Dash attendees who will have the opportunity to organise small local meet-ups for collaboration and social events.
+Meaning, rather than committing their entire working day, participants can choose one or multiple 2.5 hour short collaborative co-working calls, called "contribution sessions" each day based on their availability.
+In the future, we will co-design hybrid events with an "online-first" approach for the Book Dash attendees who will have the opportunity to organise small local meet-ups for collaboration and social events.
```{figure} ../figures/first-pull-request.*
---
@@ -20,13 +20,13 @@ Making your first pull request on GitHub.
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
-## Inviting Diverse Contributions
+## Inviting diverse contributions
Our Book Dash attendees are:
- First time Book Dash attendees who have previously interacted with the project or community who send in their application describing where/how in the project and community they would like to contribute. See the {ref}`eligibility` section for details.
-- Previous Book Dash attendees to express their interest to participate again as a contributors, members of planning committee and/or mentors. Book Dash mentors facilitating other attendees' contributions in one or multiple of the contribution sessions based on their interest and availability.
+- Previous Book Dash attendees to express their interest to participate again as contributors, members of planning committees and/or mentors. Book Dash mentors facilitating other attendees' contributions in one or multiple of the contribution sessions based on their interest and availability.
-As a community-driven guidebook, _The Turing Way_ aims to co-create contents that are comprehensible and beneficial for the wider community of researchers, data scientists and individuals working in research infrastructure roles.
+As a community-driven guidebook, _The Turing Way_ aims to co-create content that is comprehensible and beneficial for the wider community of researchers, data scientists and individuals working in research infrastructure roles.
Hence, _The Turing Way_ specifically welcomes contributors from diverse fields, identities, and backgrounds who can propose ideas and work on new aspects of an existing chapter or create new chapters in its guides.
All the contributions are managed through GitHub.
@@ -47,7 +47,7 @@ The skills and contributions that we invite at the Book Dash include, but are no
- Storytelling skills that can help make our content more engaging.
(ch-bookdash-eligibility)=
-## Eligibility: Who Should Apply to Join the Book Dash
+## Eligibility: who should apply to join the Book Dash?
We want to support participants in getting the most out of these Book Dash events.
Therefore, we encourage applications from members of our community, including both new and existing contributors.
@@ -58,28 +58,28 @@ Some familiarity with the project and how we work in the community will help our
If you have previously contributed to a collaborative project or have a specific proposal for contribution in mind, you are highly encouraged to apply.
Do get in touch with one of the core contributors who can help you shape your idea by identifying where and how they fit in the bigger vision of the project.
-If you have not interacted with our community before, but want to take part in a Book Dash, please join one of our community events such as {ref}`Co-working calls` call or {ref}`Collaboration Cafés`,.
+If you have not interacted with our community before, but want to take part in a Book Dash, please join one of our community events such as {ref}`Co-working calls` call or {ref}`Collaboration Cafés`.
This way, you will get to know about our project and understand more about how you could contribute during a Book Dash.
-## Support In-Person, Hybrid and Remote Participation
+## Support in-person, hybrid and remote participation
-Previous Book Dashes have been organised for in-person participation in venues located in the UK (home country of the project), as hybrid events, or entirely online.
+Previous Book Dashes have been organised for in-person participation in venues located in the UK (the home country of the project), as hybrid events, or entirely online.
**For participants attending a Book Dash in person:**
-* All the participants who need to travel to the event's venue are offered financial support to cover their travel, accommodation, and related expense such as childcare or special accessibility requirements.
-* In the past, due to the funding model of _The Turing Way_, we had to limit our selection to the contributors within European countries.
+* All the participants who need to travel to the event's venue are offered financial support to cover their travel, accommodation, and related expenses such as childcare or special accessibility requirements.
+* In the past, due to the funding model of _The Turing Way_, we had to limit our selection to contributors within European countries.
**For participants attending a Book Dash remotely:**
* We have experimented with hybrid (partial remote) participation where one of the participants coordinated with their team remotely.
Based on the success of this hybrid format and further demand for more remote participation, we have had two virtual events that did not involve travel.
In the future, we aim to experiment with a multi-hub format allowing multiple small groups across the globe to meet in person as they work synchronously with other international contributors remotely.
* Financial support is made available to support the remote accessibility requirements of the participants at hybrid and fully remote Book Dashes.
-It includes (but not be limited to) temporary access to high-speed internet, childcare grant and live transcription during the event.
-These bursaries are also available for rent or purchasing small hardware such as headphones or webcam to enhance participants overall experience.
-* There is also financial support for subsistence costs such as buying meals or treat for the online social events during the Book Dash.
+It includes (but is not limited to) temporary access to high-speed internet, childcare grants and live transcription during the event.
+These bursaries are also available for the rent or purchase of small hardware items such as headphones or webcams to enhance participants' overall experience.
+* There is also financial support for subsistence costs such as buying meals or treats for the online social events during the Book Dash.
## More Resources on Book Dash
In this chapter, we discuss the {ref}`application`, {ref}`event preparation and participant selection` and {ref}`event preparation` processes.
-All the templates related to book dash is provided in the {ref}`community template collection`.
+All the templates related to book Dashes are provided in the {ref}`community template collection`.
From c796e876ae754f336464d937504b5d80a8e2dd1c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:25 +0000
Subject: [PATCH 040/142] Update source file bookdash-after.md
---
.../community-handbook/bookdash/bookdash-after.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-after.md b/book/website/community-handbook/bookdash/bookdash-after.md
index 989630df429..a446c511fb2 100644
--- a/book/website/community-handbook/bookdash/bookdash-after.md
+++ b/book/website/community-handbook/bookdash/bookdash-after.md
@@ -9,8 +9,8 @@ Also, we share with them some ways they can stay connected and keep contributing
## Joining the ongoing efforts
With every new effort initiated by our members, we gain new insights to improve our global outreach.
-These efforts often start in our [GitHub issue](https://github.com/the-turing-way/the-turing-way/issues) section.
-These are good places to begin new discussions by creating a new issue or join the ongoing discussion by commenting on the issue.
+These efforts often start in our [GitHub issues](https://github.com/the-turing-way/the-turing-way/issues) section.
+These are good places to begin new discussions by creating a new issue or join the ongoing discussion by commenting on an issue.
If our contributors want to start to get to know the project or want to return after a long break, they can begin with our good first issues.
If they have a new idea that they would like to add to the project as a new section in an existing chapter, or as a whole new chapter, they can start by creating a new issue.
@@ -22,7 +22,7 @@ Everyone interested in learning from or developing this project can join us for
Participants can sign up on this HackMD to attend the upcoming calls: https://hackmd.io/@KirstieJane/CollabCafe.
Anyone who would like to host these calls at other times, please get in touch with the team members.
-See more details in the chapter {ref}`Coworking Call`
+See more details in the {ref}`Coworking Calls` chapter.
## Reviewing open pull requests
@@ -32,19 +32,19 @@ They can join discussions on these pull requests or help in exploring resources
## Representing _The Turing Way_ in your community/conference
If our attendees would like to represent our community, they can connect with _The Turing Way_ team for support and assistance in drafting an abstract and help them prepare to deliver a short workshop or presentation.
-This is another contribution that can be discussed and prepared collaboratively during our Collaboration cafe or coworking calls.
+This is another contribution that can be discussed and prepared collaboratively during our Collaboration Cafe or coworking calls.
## Connecting through social media
Everyone is welcome to join our [Slack workspace](https://theturingway.slack.com/) for informal discussions.
They can also sign up to receive our monthly newsletter: [https://tinyletter.com/TuringWay/](https://tinyletter.com/TuringWay/).
-We are on Twitter as [@turingway](https://twitter.com/turingway), where we send regular updates.
+We are on X (formerly Twitter) as [@turingway](https://twitter.com/turingway), where we send regular updates.
If you have more ideas or questions about the project, the Book Dash event or something else related to our community, please feel free to reach out to the team members [theturingway@gmail.com](mailto:theturingway@gmail.com).
## Reports and additional materials
-- All the templates related to Book Dash is provided in the {ref}`community template collection`
+- All the templates related to Book Dashes are provided in the {ref}`community template collection`
- [_The Turing Way_ Report By Malvika Sharan with team members from November 2020](https://github.com/the-turing-way/the-turing-way/blob/book-dash-chapter/workshops/book-dash/book-dash-nov20-report.md)
- CSCCE blog post by Arielle Bennett, July 2020: [Book Dashes: Collaborative Community Events](https://www.cscce.org/2020/07/09/book-dashes-collaborative-community-events/)
- Open Working blog post by Esther Plomp, February 2020: [The Turing Way Bookdash](https://openworking.wordpress.com/2020/02/27/the-turing-way-bookdash/)
From 1d7e0336cba957780bc21666d4010b557711504e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:25 +0000
Subject: [PATCH 041/142] Update source file bookdash-application.md
---
.../bookdash/bookdash-application.md | 20 +++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-application.md b/book/website/community-handbook/bookdash/bookdash-application.md
index d673b6fc1cf..440183851ad 100644
--- a/book/website/community-handbook/bookdash/bookdash-application.md
+++ b/book/website/community-handbook/bookdash/bookdash-application.md
@@ -1,7 +1,7 @@
(ch-bookdash-application)=
# Application and Review Process
-The application, review, and selection process have been developed to provide a fair opportunity for all the interested members to show their interest in attending our book dash events.
+The application, review, and selection processes have been developed to provide a fair opportunity for all the interested members to show their interest in attending our book dash events.
In this subchapter, we have provided details on the book dash's application and reviewing process.
@@ -12,7 +12,7 @@ The event is divided into multiple sessions with small groups of participants at
This allows the core team members to offer specific mentorship to the invited participants and make this an interactive, intimate, fun, and productive event.
To fairly make this selection, a call for applications is opened at least two months in advance so that interested members can share their skills, interest, and expected outcomes through a short application.
-The applications are kept open for a minimum of 4 weeks and the timeline is communicated clearly through our newsletters, Twitter feed, and application form.
+The applications are kept open for a minimum of 4 weeks and the timeline is communicated clearly through our newsletters, X (formerly Twitter) feed, and application form.
This application can take 30-45 minutes to complete.
We have created this template document with all the questions to prepare a draft before submission: https://tinyurl.com/tw-bookdash-template.
@@ -26,13 +26,13 @@ We ask if applicants have previously participated in a Book Dash so that they ca
> We encourage returning applicants to The Turing Way Book Dash to join the planning committee. They will take on advisory and leading roles for the Book Dash events in 2022 by getting involved in application Review, selection process, organisation meeting, session host and mentorship or accessibility-related support they can offer based on their willingness, availability and interest. For any questions, please email theturingway@gmail.com.
In 150 words each, applicants respond to the following mandatory questions:
-- What could you contribute to The Turing Way during the book dash event?
-- What would you gain from being part of The Turing Way book dash event?
+- What could you contribute to _The Turing Way_ during the book dash event?
+- What would you gain from being part of _The Turing Way_ book dash event?
-We ask an optional question for returning members to express their interest to take on leadership roles in designing and organising Book Dashes:
+We ask an optional question for returning members to express their interest in taking on leadership roles in designing and organising Book Dashes:
- How would you like to collaborate with other participants, or what support will you invite from them during the Book Dash event?
-These responses to the questions in the application form help us select a group of people who will be able to work effectively together and cover a broad set of possible contributions to the Turing Way.
+These responses to the questions in the application form help us select a group of people who will be able to work effectively together and cover a broad set of possible contributions to _The Turing Way_.
We don't expect that the candidates might have previously contributed to the project, but some familiarity with our project infrastructure such as GitHub-based contributions will be helpful.
We are looking to support ideas on what our participants think is important and helpful for others doing reproducible research and data science in the current scenario.
@@ -56,7 +56,7 @@ Scoring for each criterion is done between 1 to 3, where 3=criteria fully met, 2
To avoid personal bias, each of these scores is clearly defined for every question in the review response form, which is explained below.
This rubric aims to evaluate the application across multiple aspects and avoid any personal bias panel members may have.
-*This rubric is adapted from the [Mozilla Open Leadership](https://foundation.mozilla.org/en/initiatives/mozilla-open-leaders/) and the [Open Life Science](https://openlifesci.org/) programs*
+*This rubric is adapted from the [Mozilla Open Leadership](https://foundation.mozilla.org/en/initiatives/mozilla-open-leaders/) and the [Open Life Science](https://openlifesci.org/) programs*.
(ch-bookdash-application-rubrics)=
### Rubrics for scoring applications
@@ -81,7 +81,7 @@ Based on their evaluation of the applications they will provide scores for diffe
| Sections | Score 1 | Score 2 | Score 3 |
| -------- | ------- | ------- | -------:|
-| **Readiness for the book dash event** | (not ready) Does not provide enough information or seems to misunderstand the nature of _The Turing Way_ project and this event in general | (enthusiastic) Seems to have a clear understanding of _The Turing Way_ project and this event and brings along a specific content for contributions | (clear) Seems to have a clear understanding of the Turing Way project and this event and a clear understanding of how they can contribute and collaborate with each other at this event |
+| **Readiness for the book dash event** | (not ready) Does not provide enough information or seems to misunderstand the nature of _The Turing Way_ project and this event in general | (enthusiastic) Seems to have a clear understanding of _The Turing Way_ project and this event and brings along a specific content for contributions | (clear) Seems to have a clear understanding of _The Turing Way_ project and this event and a clear understanding of how they can contribute and collaborate with each other at this event |
| **Goals for the project contributions:** | (not ready) Shares vague or general ideas that are unrelated to _The Turing Way_ project and this event, or no goals at all | (enthusiastic) Shares clear, overly ambitious ideas for _The Turing Way_ project and this event that can likely be refined in a collaboration cafe, or the day before the event during the brainstorm session | (clear) Shares clear, achievable contribution/development ideas for this event that fits _The Turing Way_ project and are likely to be achieved through the applicant’s participation |
| **Purpose of participation and what they will get out of the book dash:** | (not ready) Purposes for participation at the book dash seem almost entirely self-centered and about the applicant’s status, rather than about participating in _The Turing Way_ community to develop the project | (enthusiastic) Purposes for the participation at the book dash event are not completely clear from the application or are limited (even though useful), such as typo or bug fixing | (clear) Purposes for participation at the book dash event are valuable in many ways and are likely to help the applicant to become an active contributor and take ownership of their work in _The Turing Way_ project and in the broader ecosystem in their own rights |
| **Willingness to collaborate and contribute after the book dash:** | (not ready) Seems closed to collaborative ways of working or more interested in only one aspect of data science, research or related topic | (enthusiastic) Seems excited to learn from others and _The Turing Way_ project, but in a general way without much understanding of what those things mean yet | (clear) Seems excited to collaborate with others and is motivated to contribute to _The Turing Way_ community |
@@ -90,14 +90,14 @@ The following sections are aimed at collecting open-ended response by the review
We ask all reviewers to finish the review by describing the application, representation aspects of the applicant and the motivations for their scores to facilitate conversation during the selection panel discussion under these questions.
-```
+```markdown
- Please highlight any diversity/minority groups this applicant belong to, that should be represented at this event
- Please provide 1-2 summary sentences about this application to facilitate discussion during the selection panel
```
Reviewers are also asked to disclose if any conflict of interest may have influenced their review leading to any bias in their decision.
-```
+```markdown
- Please state if you have any conflict of interest with the proposal described in this application or do you know this applicant personally that may lead to a biased decision
```
From 51b48b225c160c5d679f66be41bf974dc3cd5f41 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:26 +0000
Subject: [PATCH 042/142] Update source file bookdash-events.md
---
.../bookdash/bookdash-events.md | 40 +++++++++----------
1 file changed, 20 insertions(+), 20 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-events.md b/book/website/community-handbook/bookdash/bookdash-events.md
index fd34e0abac3..50add3416db 100644
--- a/book/website/community-handbook/bookdash/bookdash-events.md
+++ b/book/website/community-handbook/bookdash/bookdash-events.md
@@ -6,37 +6,37 @@ These events include a pre-event webinar for information, onboarding calls, GitH
_The Turing Way_ participation guidelines, [Code of Conduct](https://the-turing-way.netlify.app/community-handbook/coc.html) and [Contribution guideline](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md) apply to all these events:
-## Pre-Event Calls
+## Pre-event calls
-### Webinar for Information
+### Webinar for information
The planning committee members will host one webinar to share information about the Book Dash that can help interested members to plan their proposals for the event.
These webinars will include a 10-15 minutes introduction talk followed by a session to address any questions participants may have.
Recording and notes from this session will be published on the YouTube channel of _The Turing Way_.
-### Pre-event Onboarding Calls
+### Pre-event onboarding calls
-The planning committee will host two onboarding calls, minimum of one week before the main event to ensure that all the participants are made familiar with the project, the format of the book dash, and how they can be contributing through their involvement at the book dash.
+The planning committee will host two onboarding calls, minimum of one week before the main event to ensure that all the participants are made familiar with the project, the format of the book dash, and how they can be contributing through their involvement at the Book Dash.
It is an opportunity for the organising team and the selected attendees to get to know each other and discuss any concerns that they may have before the book dash.
Several participants often come to these calls with some plans and topics they would like to explore for their contributions in _The Turing Way_.
Therefore, the host of this call facilitates a breakout session to allow attendees to draft their [SMART goals](https://www.atlassian.com/blog/productivity/how-to-write-smart-goals) for the Book Dash.
-These topics can be something that is either missing in the existing chapters or need to be updated in the project.
+These topics can be something that is either missing in the existing chapters or needs to be updated in the project.
We also discuss _The Turing Way_ as a project in general and what the core team is working on to support the development of its guide on reproducibility, ethics, project design, collaboration, communication and a meta-book on the project itself.
-Most importantly, the core team goes through the contribution guideline and explain how attendees can effectively use their time at the book dash.
+Most importantly, the core team goes through the contribution guideline and explains how attendees can effectively use their time at the Book Dash.
The template for shared notes can be accessed in the community handbook {ref}`here`.
You can read notes from the calls from the most recent book dash [here](https://hackmd.io/@turingway).
-### GitHub Introduction Session
+### GitHub introduction session
One week before the Book Dash, 2-3 members from the planning committee will host a skill-up session for members who don't have any prior experience with GitHub.
At this call, participants will learn how to:
- create a new repository
- create a (README) file: introduction to Markdown
-- submit changes (to The Turing Way) via Pull Request (PR)
-- see how to review PR or create issues
+- submit changes (to _The Turing Way_) via a Pull Request (PR)
+- see how to review PRs or create issues
This session will help participants identify resources that they can use for self-paced learning.
In the previous events, we have used the following materials:
@@ -46,9 +46,9 @@ In the previous events, we have used the following materials:
## During the Book Dash
-### Contribution Sessions
+### Contribution sessions
-On each day of Book Dash, we will hold three 2.5 hour-long contribution sessions when hosting virtually each followed by a break or social event.
+On each day of the Book Dash, we will hold three 2.5 hour-long contribution sessions when hosting virtually each followed by a break or social event.
Each contribution session will follow the Pomodoro technique for coworking that we also use for the {ref}`coworking calls` using the [browser-based shared (cuckoo) clock](https://cuckoo.team/tw-bookdash) to coordinate the time.
In the opening session of the first day, one of the planning committee members will provide an overview of _The Turing way_ project and the resources that are available for the participants for their book dash contributions.
@@ -58,31 +58,31 @@ Participants are also encouraged to come up with the main sections of their cont
The rest of the contribution sessions throughout the Book Dash will be facilitated in breakouts allowing members with similar ideas to collaborate.
Participants can also work in self-organised groups or individually on their contribution ideas with the support of mentors.
-This is also a chance for everyone to meet the participants and helpers informally, learn about each other and connect with specific members who plan to work on the related topic during the book dash.
+This is also a chance for everyone to meet the participants and helpers informally, learn about each other and connect with specific members who plan to work on the related topic during the Book Dash.
Participants will be supported to collaborate in small groups, organising their thoughts and ideas for contributions during or after the Book Dash.
Each contribution session will end with participants sharing their work with others and identifying new collaborators based on the similarity of their interests.
For participants who are unfamiliar with GitHub or would like a refresher (and did not manage to attend the GitHub introduction session), the planning committee members will guide them through the process of making their first pull request.
-### Social Sessions
+### Social sessions
There will also be themed social discussion or networking session where participants can interact with others, continue their discussions outside the contribution session or take a break as it's most sustainable and helpful for their participation.
For a virtual Book Dash, a support fund will be provided to cover the subsistence cost including paying for meals for the social sessions.
If hosting an in-person event, the core team members will plan a dinner or social event to allow participants to relax after an intense discussion session and enjoy meals together in an informal setting.
-### Reporting and Documentation
+### Reporting and documentation
At the end of each day, participants can gather all their contributions on _The Turing Way_ GitHub repository (issues, pull requests and notes) and add that in the shared notes.
Specifically, during the last contribution session, they will be asked to add their details to the [contributors](https://github.com/the-turing-way/the-turing-way/tree/book-dash-chapter/contributors.md) file and provide anonymous feedback on a {ref}`Pluses and Delta` notes.
This will help the planning committee to collect notes for their final report and improve future events.
-### Community Share-Outs & Contributor Celebration
+### Community Share-outs & Contributor Celebration
On the last day of the Book Dash, _The Turing Way_ team along with the planning committee members host Community Share-out and Contributor Celebration sessions that are open to the public.
The Community Share-out events provide a public platform to openly recognise the work of our attendees and community contributors.
In this session, all the interested contributors including the Book Dash attendees will have a chance to share their work with everyone through a short demo/presentation.
-All Book Dash attendees are encouraged to invite their colleagues and friends who would like to learn about and celebrate their work and connect with The Turing Way community.
+All Book Dash attendees are encouraged to invite their colleagues and friends who would like to learn about and celebrate their work and connect with _The Turing Way_ community.
These sessions are generally recorded to share via the project's YouTube channel.
@@ -91,10 +91,10 @@ These sessions are generally recorded to share via the project's YouTube channel
We acknowledge that everyone prefers different settings to work effectively and attentively.
Therefore we create an environment for self-paced contributions to _The Turing Way_ project.
-Some recommendations to achieve this by managing the space at the book dash by:
-- set up shared notes for everyone to take notes together and draw inspiration from each other's work (see {ref}`template for notes`).
-- offering a separate space (physical space or online breakout room) for open discussion for people who work better by discussing their ideas out loud.
-- when meeting in person, providing semi-quiet spaces or headphones for noise cancellation for people who don't need active discussions.
+Some recommendations to achieve this by managing the space at the Book Dash:
+- Set up shared notes for everyone to take notes together and draw inspiration from each other's work (see {ref}`template for notes`).
+- Offer a separate space (physical space or online breakout room) for open discussion for people who work better by discussing their ideas out loud.
+- When meeting in person, provide semi-quiet spaces or headphones for noise cancellation for people who don't need active discussions.
Throughout the day, everyone is encouraged to ask for help, move around or change their position or group as needed.
Participants are invited to offer feedback on other people's work during the report out session.
From aa30e6a3430d014d4fd1ce29f29d2b5198a48863 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:26 +0000
Subject: [PATCH 043/142] Update source file bookdash-illustrator.md
---
.../bookdash/bookdash-illustrator.md | 32 +++++++++----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-illustrator.md b/book/website/community-handbook/bookdash/bookdash-illustrator.md
index 6ee98180d43..1777e71fb46 100644
--- a/book/website/community-handbook/bookdash/bookdash-illustrator.md
+++ b/book/website/community-handbook/bookdash/bookdash-illustrator.md
@@ -15,7 +15,7 @@ The Book Dash was a success and the experience of working with an artist added t
They loved seeing their ideas translated into images - an (almost) immediate output they could collaborate on and feel proud to have contributed to.
This experience was brought back in subsequent Book Dash events in person and online and has always remained a highlight.
-```{figure} https://github.com/the-turing-way/the-turing-way/raw/main/workshops/book-dash/figures/book_dash_mcr_art.*
+```{figure} ../../../../workshops/book-dash/figures/book_dash_mcr_art.*
---
height: 400px
name: book_dash_mcr_art
@@ -24,18 +24,18 @@ alt: A set of hand-drawn sketches about stuck horizontally against a textured wo
Picture taken by Jez Cope at the Book Dash 2019 in Manchester. Hand sketched illustrations by Matthew Kemp of [Scriberia](http://www.scriberia.co.uk/).
```
-All illustrations generated within *The Turing Way* are shared under the CC-BY 4.0 license on Zenodo: [https://zenodo.org/record/3332807](https://zenodo.org/record/3332807).
+All illustrations generated within *The Turing Way* are shared under the CC-BY 4.0 licence on Zenodo: [https://zenodo.org/record/3332807](https://zenodo.org/record/3332807).
All images on Zenodo are shared in the original format and size, but we use smaller files in *The Turing Way* guides that you can find in [our GitHub repository](https://github.com/the-turing-way/the-turing-way/tree/main/book/website/figures).
When citing, please include the following attribution with the specific DOI as listed on the particular Zenodo page.
> _This illustration is created by Scriberia with The Turing Way community. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807)_
-When using these illustrations in a digital document, please describe them using Alt Text feature for the users of screen reading apps.
+When using these illustrations in a digital document, please describe them using the Alt Text feature for the users of screen reading apps.
Alt Text is an important criteria to ensure accessible web design used for describing abstract concepts captured in images to readers who are unable to see them.
-For guidance, please read [Write good Alt Text to describe images](https://accessibility.huit.harvard.edu/describe-content-images) by Digital Accessibility service of Harvard University.
+For guidance, please read [Write good Alt Text to describe images](https://accessibility.huit.harvard.edu/describe-content-images) by the Digital Accessibility service of Harvard University.
We encourage using these illustrations not just within *The Turing Way*, but wherever appropriate in the context of science communications or to enhance public engagement with data science and research.
-We already see the reuse by the broader community of researchers, science communicators, policymakers and more, as reflected by over 12,000 downloads at the time of writing this chapter (July 2022).
+We already see reuse by the broader community of researchers, science communicators, policymakers and more, as reflected by over 12,000 downloads at the time of writing this chapter (July 2022).
Here are some examples:
- **Scoping Report: EU Policy**: [Reproducibility of scientific results in the EU: scoping report. Publications Office of the European Union](https://op.europa.eu/en/publication-detail/-/publication/6bc538ad-344f-11eb-b27b-01aa75ed71a1), Directorate-General for Research and Innovation (European Commission), author(s): Baker, L., Cristea, I. A., Errington, T. M., Jaśko, K., Lusoli, W., MacCallum, C. J., Parry, V., Pérignon, C., Šimko, T., Winchester, C. (2020)
@@ -46,7 +46,7 @@ Here are some examples:
- **News article**: [Connecting the dots between research methods, academic cultures and technical solutions: Three reflections on publishing reproducible research outputs - News - Knowledge Exchange](https://www.knowledge-exchange.info/news/articles/29-01-2021), Knowledge Exchange, Chiarelli, A. (2021)
- **Training Materials**: [Reproducible research](https://eglerean.github.io/reproducible-research/03-sharing), (2019)
-## Benefits of Illustrations and Why Hire a Professional Scribe
+## Benefits of illustrations and why hire a professional scribe
*The Turing Way* chapters often include research or scientific concepts described by professionals.
As experts, many of us do not always effictively communicate our ideas in simple terms for people who are new to those research concepts.
@@ -65,7 +65,7 @@ These illustrations are available at the end of the event, or after a few days i
Having a scribe at an event can also improve engagement and help participants contribute to something that is immediately and visually achievable in a short duration.
Furthermore, if shared on the spot, researchers can use their illustrations as a way to exchange their ideas more widely, even with those they won't meet.
-### Considerations for Creating a Brief
+### Considerations for creating a brief
Finding a good illustrator or scribe can be a new challenge if you have not worked with one before.
It is always useful to ask in your network if someone has previously worked with someone who they may recommend. The cost may vary based on the country, type of service or experience of the scribe/company.
@@ -84,35 +84,35 @@ Your request/brief may include the following details:
- what kind of details do you need to include that should be maintained consistently in all illustrations
- If you need raw and vector (layered) versions of your image files, you will have to communicate this in advance and prepare to pay extra for the postprocessing.
-### Service Providers
+### Service providers
-Budget for hiring a professional scribe can vary based on the kind of service they provide.
-In *The Turing Way*, we have worked with [Scriberia](https://www.scriberia.com/) artists/scribes who are hired on per day cost for live scribing.
+The budget for hiring a professional scribe can vary based on the kind of service they provide.
+In *The Turing Way*, we have worked with [Scriberia](https://www.scriberia.com/) artists/scribes who are hired on a per day cost for live scribing.
The cost is less for half-day, and additional charges apply for infographics.
For each event, we have worked with different scribes and enjoy the diverse style and skills they bring to the event.
Our illustrations are a mix of simple and complex concepts and are often described with cartoon-like characters.
The Scribria company is given equal authorship with *The Turing Way* community members who contribute to the development of those images during the Book Dash.
-Costs of hiring freelance illustrators may be lower and they can often provide bespoke services (creating specific styles, details and number of images).
+The costs of hiring freelance illustrators may be lower and they can often provide bespoke services (creating specific styles, details and number of images).
Our colleagues in [Turing Commons](https://turing-commons.netlify.app/) work with freelance scribe artists and illustrators to create illustrations asynchronously.
-All images by Turing Commons are available in their [GitHub repository](https://github.com/alan-turing-institute/ethics-and-rri-resources/tree/main/images) also under CC-BY 4.0 license for reuse.
+All images by Turing Commons are available in their [GitHub repository](https://github.com/alan-turing-institute/ethics-and-rri-resources/tree/main/images) also under a CC-BY 4.0 licence for reuse.
-When planning, it is always good to look for more than one service providers to compare the cost.
+When planning, it is always good to look for more than one service provider to compare the cost.
Contact the company's account manager or the freelance artist directly to set a 20-30 minutes meeting to discuss your brief and any detail they should know.
Based on your request, they will share their quotes for each service.
When confirmed, block the dates/times and share details about your event (agenda, logistics, and anything else they should know).
When agreed, you will receive a contract for the service, terms and conditions and an invoice to be paid after the service is delivered.
-## Pro Tips
+## Pro tips
To enhance the use of these illustrations, we have learned to keep the concepts simple, self-contained and reusable in different contexts.
If texts or sentences are used in the image, we request a copy of those illustrations without text to make sure that they can be translated into other languages.
-Images (both versions: with and without text) are uploaded on Zenodo with descriptive names as individual images in 'jpg' format to allow preview and zipped folder in different file formats to allow downloading. See details here: https://zenodo.org/record/3332807.
+Images (both versions: with and without text) are uploaded to Zenodo with descriptive names as individual images in 'jpg' format to allow preview and a zipped folder in different file formats to allow downloading. See details here: https://zenodo.org/record/3332807.
We ensure that the characters in the images are designed while maintaining representations of our diverse community members.
-### Translating and editing for reusing Images
+### Translating and editing for reusing images
Zipped archives (names ending with '-without-text.zip' on Zenodo) are provided that can be translated into languages that you would like to use.
We encourage the use and re-use of these images as much as possible.
From 6cc9b9f8ff328fc4267648d0600315a61a9c9b5e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:27 +0000
Subject: [PATCH 044/142] Update source file bookdash-logistics.md
---
.../community-handbook/bookdash/bookdash-logistics.md | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-logistics.md b/book/website/community-handbook/bookdash/bookdash-logistics.md
index b0d9ad78dad..ae949024fef 100644
--- a/book/website/community-handbook/bookdash/bookdash-logistics.md
+++ b/book/website/community-handbook/bookdash/bookdash-logistics.md
@@ -1,6 +1,6 @@
# Book Dash Logistics
-We have created the following checklists, which are chronologically structured to help organise Book Dash online or in-person.
+We have created the following checklists, which are chronologically structured to help organise Book Dash events online or in-person.
## Before the Event
@@ -22,7 +22,7 @@ We have created the following checklists, which are chronologically structured t
* Find volunteers from the organisers who would like to run social events (discussion session, meal, informal chat) - During the event
* Find volunteers from the organisers who would like to run community share out sessions - on the last day
* Check with them if there is anything else they would like to suggest or get involved in
-- [ ] Announce in the newsletter and promote on Twitter at least 2-3 months in advance
+- [ ] Announce in the newsletter and promote on X (formerly Twitter) at least 2-3 months in advance
- [ ] Think about who else needs to be invited, like Artists, speakers, more diverse participants
- [ ] Identify helpers from the core members and invite them
- [ ] Send a reminder in next newsletters with more details if needed
@@ -40,7 +40,6 @@ We have created the following checklists, which are chronologically structured t
- [ ] Provide details on Code of Conduct, contribution guideline and ways to get involved in an ongoing discussion
- [ ] Host the onboarding call one week before the event to share logistics and facilitate the drafting of SMART goals
- [ ] Group participants into the proposed working groups as per their SMART goals from the onboarding call
-- [ ] Host the onboarding call one week before the event to share logistics and facilitate the drafting of SMART goals
- [ ] Send a reminder email to register on Eventbrite sharing important links and information including support grant, GitHub session, onboarding call info and reimbursement process
- [ ] Create a GitHub issue to collect bio and highlight of the participants to add them to the Contributors Record
@@ -82,7 +81,7 @@ We have created the following checklists, which are chronologically structured t
- [ ] If an artist, illustrator or consultant is invited, coordinate the schedule with participants so they have the chance to engage
- [ ] Run a social session each day
* These are run by organisers to ensure everyone has the chance to connect informally
-- [ ] Host community share out the event on the last day to demonstrate and celebrate the contributions made by everyone during the Book Dash
+- [ ] Host community share out event on the last day to demonstrate and celebrate the contributions made by everyone during the Book Dash
- [ ] Ask for feedback on the last day (plus and delta)
- [ ] Share the GitHub issue for adding bio and highlight
- [ ] Take screenshots or group photos (with permission) to share in reports or social media
From 82ab4072d6ed00790ecab40227c60d77c92cb219 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:27 +0000
Subject: [PATCH 045/142] Update source file bookdash-selection.md
---
.../community-handbook/bookdash/bookdash-selection.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/book/website/community-handbook/bookdash/bookdash-selection.md b/book/website/community-handbook/bookdash/bookdash-selection.md
index 3c1f9788361..897535639df 100644
--- a/book/website/community-handbook/bookdash/bookdash-selection.md
+++ b/book/website/community-handbook/bookdash/bookdash-selection.md
@@ -6,13 +6,13 @@ This subchapter explains the process of selection and logistics for organising t
## Selection of Book Dash Planning Committee
To ensure that the Book Dash continues to evolve as per the community needs and preferences, invite returning members of the Book Dash events to join a planning committee.
-Members of the Book Dash planning committee participate in the planning meetings, provides feedback on the ongoing process and when possible takes the lead on organisation tasks related to the Book Dash.
+Members of the Book Dash planning committee participate in the planning meetings, provide feedback on the ongoing process and when possible take the lead on organisation tasks related to the Book Dash.
These tasks usually include the following roles and responsibilities:
-- **Planning Meeting**: attend a planning meeting to help select a date, agree on the format and share any feedback on the previous event that can help plan the Book Dash(time commitment: up to 30 minutes)
+- **Planning Meeting**: attend a planning meeting to help select a date, agree on the format and share any feedback on the previous event that can help plan the Book Dash (time commitment: up to 30 minutes)
- **Application Review**: review 2-3 applications based on your availability (time commitment: up to 30 minutes)
- **Selection meeting**: participate in the selection meeting to help ensure that the selection is equitable (time commitment: 1.5-2 hours)
-- **Organisation meeting**: attend 1 call to finalise the logistics for the organisation (program agenda and participant support will be carried out by The Turing Way core members) (time commitment: 1 hour)
+- **Organisation meeting**: attend 1 call to finalise the logistics for the organisation (program agenda and participant support will be carried out by _The Turing Way_ core members) (time commitment: 1 hour)
- **Session host and mentorship**: lead one of the 2 onboarding calls or one GitHub introduction session before and 1-2 of the contribution sessions or social sessions during the Book Dash based on their schedule (three 1.5 to 2.5 hour-long sessions)
- **Debrief meeting**: attend a meeting after the event to discuss what went well and what we can improve going forward (time commitment: 1 hour)
- **Shared Documents**: set up or review shared notes, application form, review rubrics or other required documents for the Book Dash (time commitment: relative to the type of document)
@@ -21,11 +21,11 @@ These tasks usually include the following roles and responsibilities:
The invitation to join the planning committee is sent by the core team members based on the applications sent by returning members of the Book Dash expressing their interest in mentoring.
This is a volunteer position and there are no expectations of commitment to do multiple tasks described above.
-## Selection of Book Dash Participants
+## Selection of Book Dash participants
The Book Dash Planning Committee meets after they have individually scored the applications using the rubrics defined in the previous subchapter.
They agree upon a final set of applicants selected to participate in the Book Dash.
-The panel members also create constructive feedback on the application that can be shared with the applicants who were not selected so that they can assess other pathways to engage with the project and core team.
+The panel members also create constructive feedback on the applications that can be shared with the applicants who were not selected so that they can assess other pathways to engage with the project and core team.
All applicants are contacted at least 4 weeks in advance to ensure that they can assess their situation and availability for the Book Dash.
From dd61e89058dfa8fb35299920cb2dfdb652550dba Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:28 +0000
Subject: [PATCH 046/142] Update source file coc-details.md
---
book/website/community-handbook/coc/coc-details.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/coc/coc-details.md b/book/website/community-handbook/coc/coc-details.md
index 3f96589ed42..4f7adc4ac28 100644
--- a/book/website/community-handbook/coc/coc-details.md
+++ b/book/website/community-handbook/coc/coc-details.md
@@ -47,7 +47,7 @@ Examples of unacceptable behaviour by Turing Way community members at any projec
Participants who are asked to stop any inappropriate behaviour are expected to comply immediately.
This applies to all Turing Way community events and platforms, either online or in-person.
-If a participant engages in behaviour that violates this Code of Conduct, any member of the core development team may warn the offender, ask them to leave the event or platform (without refund), or impose any other appropriate sanctions (see the [enforcement manual](#4-enforcement-manual) for details).
+If a participant engages in behaviour that violates this Code of Conduct, any member of the core development team may warn the offender, ask them to leave the event or platform (without refund), or impose any other appropriate sanctions (see the [enforcement manual](ch-coc-enforcement) for details).
## 2.4 Feedback
From d83f4178e1f7c54790e270bcf1742de75654e823 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:29 +0000
Subject: [PATCH 047/142] Update source file coc-enforcement.md
---
book/website/community-handbook/coc/coc-enforcement.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/coc/coc-enforcement.md b/book/website/community-handbook/coc/coc-enforcement.md
index d10f8f015e3..0447541c34b 100644
--- a/book/website/community-handbook/coc/coc-enforcement.md
+++ b/book/website/community-handbook/coc/coc-enforcement.md
@@ -62,4 +62,4 @@ However, the CoC committee is not required to act on this feedback.
## 4.5 Conflicts of Interest
-If the report is about someone is the committee, please send the report to the other individuals on the committee.
+If the report is about someone on the committee, please send the report to the other individuals on the committee.
From 62de212205a6757fa9ec34ff7d16a012603c6adb Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:29 +0000
Subject: [PATCH 048/142] Update source file communication-channels.md
---
.../website/community-handbook/communication-channels.md | 9 +++++++++
1 file changed, 9 insertions(+)
create mode 100644 book/website/community-handbook/communication-channels.md
diff --git a/book/website/community-handbook/communication-channels.md b/book/website/community-handbook/communication-channels.md
new file mode 100644
index 00000000000..c9aedba913f
--- /dev/null
+++ b/book/website/community-handbook/communication-channels.md
@@ -0,0 +1,9 @@
+(ch-communication-platforms)=
+
+# Communication Platforms
+
+_The Turing Way_ delivery team uses a number of communication platforms to share the work of the community outwards, and to communicate in real-time as well (alongside GitHub, which hosts the project repository and all sorts of updates).
+
+Examples of this may include social media platforms, as well as real-time messaging services.
+
+This section aims to collect the policies and practices that we employ across our communication platforms in one place, which you are free to use for your own community platforms.
From 0c4ffa74ab661677a61d082bf1dfcd92db08d1b2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:30 +0000
Subject: [PATCH 049/142] Update source file slack-start-guide.md
---
.../communication-channels/slack-start-guide.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/book/website/community-handbook/communication-channels/slack-start-guide.md b/book/website/community-handbook/communication-channels/slack-start-guide.md
index 86ed876aec7..95d9898f2bc 100644
--- a/book/website/community-handbook/communication-channels/slack-start-guide.md
+++ b/book/website/community-handbook/communication-channels/slack-start-guide.md
@@ -4,9 +4,9 @@ Welcome to the community Slack group: a place for you to network, collaborate, e
**Table of content**
-1. [Configuring your account](#1-Configuring-your-account)
-2. [Notification settings](#2-Channel-and-Notification-settings)
-3. [Communicating with others](#3-Communicating-with-others)
+1. [Configuring your account](#1-configuring-your-account)
+2. [Notification settings](#2-channel-and-notification-settings)
+3. [Communicating with others](#3-communicating-with-others)
## 1. Configuring your account
@@ -20,7 +20,7 @@ Here is a guide to help you [edit your profile]( https://slack.com/intl/en-ca/he
### STATUS UPDATES
-Status updates can be a useful way to let others know your availability as your status will be visible to everyone in the Slack group.
+Status updates can be a useful way to let others know your availability as your status will be visible to everyone in the Slack group.
To update your status, click your name in the top left of the screen and select `update status`. You can select when you want your status update to be removed by stipulating a timeframe from the “clear after” dropdown.
You can clear a status update at any time by clicking on your name and selecting `clear status` from the dropdown.
@@ -34,7 +34,7 @@ By default, you’re automatically added to the main channels that everyone belo
You will be able to create additional channels to facilitate structured conversation. You are free to create as many channels as you would like. However, channels dedicated to projects should be made public (not private) so people can collaborate or help you.
### Configure your notifications
-Slack notifications are great, but they may bother you when you try to focus on your project. There are a lot of options for you to determine how and when you are informed about content – and at what level of granularity.
+Slack notifications are great, but they may bother you when you try to focus on your project. There are a lot of options for you to determine how and when you are informed about content – and at what level of granularity.
#### For the overall group
1. Click on your `name` at the top left of the page and select “`preferences`” from the dropdown
@@ -48,7 +48,7 @@ Slack notifications are great, but they may bother you when you try to focus on
* Here you have the option to ignore any @channel messages, or mute the channel entirely.
#### Following a specific thread
-If another group member posts something of particular interest you can choose to follow that thread. Find how to reply in thread in [Section 3](#3-Communicating-with-others).
+If another group member posts something of particular interest you can choose to follow that thread. Find how to reply in thread in [Section 3](#3-communicating-with-others).
1. Click the `ellipsis (three dots)` to the right of the original post and select “`follow message`” from the dropdown.
@@ -86,7 +86,7 @@ If a channel has become too noisy, you can additionally:
#### Message Editing & Deletion
-* You are allowed to edit your messages at any time. That means if you edit a message after someone replied to it, make it clear that you edited something if it changes the meaning of your message. See the example in the GIF below.
+* You are allowed to edit your messages at any time. That means if you edit a message after someone replied to it, make it clear that you edited something if it changes the meaning of your message. See the example in the GIF below.
### SENDING PRIVATE/DIRECT MESSAGES
It can be helpful to others when you’re sharing resources and brainstorming solutions to “work out loud” in a specific thread because then your learning becomes a future resource for others, too.
@@ -107,4 +107,4 @@ Yes, you can send files (< 1 GB) in public channels and in direct messages. See
The Slack section was adapted from a resource by BrainHackMTL and the Center for Scientific Collaboration and Community Engagement ([CSCCE](https://www.cscce.org/)) under a [CC BY 4.0 license](https://creativecommons.org/licenses/by/4.0/): [10.5281/zenodo.3763730](http://dx.doi.org/10.5281/zenodo.3763730).
-Licensed under a [CC BY 4.0 license.](https://creativecommons.org/licenses/by/4.0/)
\ No newline at end of file
+Licensed under a [CC BY 4.0 license.](https://creativecommons.org/licenses/by/4.0/)
From e8f62eb097f296b6ad6f3afd0a547cc517983010 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:30 +0000
Subject: [PATCH 050/142] Update source file slack-welcome-guide.md
---
.../slack-welcome-guide.md | 68 +++++++++++++++++++
1 file changed, 68 insertions(+)
create mode 100644 book/website/community-handbook/communication-channels/slack-welcome-guide.md
diff --git a/book/website/community-handbook/communication-channels/slack-welcome-guide.md b/book/website/community-handbook/communication-channels/slack-welcome-guide.md
new file mode 100644
index 00000000000..6bae8f945af
--- /dev/null
+++ b/book/website/community-handbook/communication-channels/slack-welcome-guide.md
@@ -0,0 +1,68 @@
+
+
+# Welcome to *The Turing Way* Slack!
+
+Slack is one of our core communication channels within the *The Turing Way* community. It is a space where folks ask questions, learn about each other's work, and get involved with *The Turing Way* and other projects. While it is not the *only* communication channel used by the community, it is a popular platform, increasingly used by remote teams around the world.
+
+*Here is a short guide to the default slack channels (meaning, you've already been added to them when you joined this space!)*:
+* [#announcements](https://theturingway.slack.com/archives/C014ZE7SKK3): Ping you about recurring community calls and community events (feel free to mute!)
+* [#ask-away](https://theturingway.slack.com/archives/C01ESKR7WN4): Use this channel to ask any question you might have - general or specific, and we'll make sure to redirect you to the right resources
+* [#community](https://theturingway.slack.com/archives/C014KE9A9LM): Topics related to the community, celebrations, collaborations, and other projects
+* [#general](https://theturingway.slack.com/archives/C014LRAK48J): For general-purpose conversations & questions
+* [#github-related-posts](https://theturingway.slack.com/archives/C014LRL27KL): For chapter ideas and discussions, as well as ongoing projects within the github repository.
+* [#ideas-for-discussion](https://theturingway.slack.com/archives/C014ZE7SL9F): For discussion and ideas, related to the guides & otherwise
+* [#introductions](https://theturingway.slack.com/archives/C014LUYEF5G): Feel free to introduce yourself here!
+* [#random](https://theturingway.slack.com/archives/C01BUPURLAW): For all other questions, comments not related to *The Turing Way*
+* [#welcome](https://theturingway.slack.com/archives/C014ZE49HH7): A bot is installed in this channel, that tags you with a random greeting & flag to represent our global community :sparkles:
+
+*There are also a number of channels dedicated to specific types of work and questions within the community (all are welcome!)*:
+
+* [#accessibility](https://theturingway.slack.com/archives/C01E654A42E): Join for discussions around accessibility practices within the community, and the upcoming work of a new working group
+* [#environmental-sustainability](https://theturingway.slack.com/archives/C04RCMAEPUZ): Join for discussions about environmental sustainability, co-hosted with the Environmental Data Science Book.
+* [#translation](https://theturingway.slack.com/archives/C01E17C1K35): Join to learn about all things translation & localisation, as well as ongoing meetings and projects within the team
+* [#infrastructure](https://theturingway.slack.com/archives/C01EUGMQSNP): Learn more about project architecture, and get involved with technical infrastructure aspects of the project
+* [#reviewers-editors-wg](https://theturingway.slack.com/archives/C043N2KSVND): Learn more about how to review & edit ongoing writing projects within *The Turing Way*
+* [#trainers-mentors-wg](https://theturingway.slack.com/archives/C0425F98E5U): Help to review ongoing promotion materials, and learn how how you can mentor other community members
+* [#user-experience](https://theturingway.slack.com/archives/C052J9UCGMP): Join the ongoing efforts around user experience and design within the community.
+
+*You might also be interested in joining the following channels*:
+* [#en-español](https://theturingway.slack.com/archives/C01DY1F5R53): Para hispanohablantes en la comunidad
+* [#events](https://theturingway.slack.com/archives/C017WM4QD24): for upcoming events in the open science network
+* [#jobs-and-opportunities](https://theturingway.slack.com/archives/C02SNNW40BZ): for jobs, workshops, and other related opportunities
+* [#reading-recommendations](https://theturingway.slack.com/archives/C0256MW3HDW): For reading recommendations from community members
+* [#research-data-management](https://theturingway.slack.com/archives/C01FATFLDPA): For folks with an interest in research data management skills, practices, and tools.
+
+*We also have Slack channels dedicated to each guide*:
+* [#guide-for-collaboration](https://theturingway.slack.com/archives/C01LUTU8FPD)
+* [#guide-for-communication](https://theturingway.slack.com/archives/C01M7APDG9X)
+* [#guide-for-ethics](https://theturingway.slack.com/archives/C01CP215WF4)
+* [#guide-for-project-design](https://theturingway.slack.com/archives/C01M7B1T95F)
+* [#guide-for-reproducibility](https://theturingway.slack.com/archives/C023KPNR2N4)
+
+If there are any other channels you'd like to see in the workspace, or ones that we use that you don't see listed here – please feel free to correct this page by making an issue or pull request on Github.
+
+## Best Practices for using Slack
+
+As with all of our communication channels, *The Turing Way* slack abides by our [Code of Conduct](https://the-turing-way.netlify.app/community-handbook/coc.html).
+
+We are in the process of developing platform-specific guidelines for Slack and other community platforms. While these are being developed, here are a few general guidelines to get you started:
+
+* **Images**: Use alt text to describe images, diagrams, or other visuals ([Learn more about how to do this in this tutorial.](https://slack.com/intl/en-gb/resources/using-slack/how-to-boost-accessibility-in-slack&utm_medium=promo)). Don't forget to add important information like context in your description!
+* **Links**: If you are inserting a link into a message, limit the number of embedded links within a message. Avoid embedding links within replies to messages when possible, as links posted within threads are not readable for screen readers.
+* **Emojis**: Limit the use of emojis that break up narrative flows of information where possible (such as emojis listed between works). Remember that not all people are able to access the emoji reactions option within Slack, and use written affirmations as well!
+* **Bandwidth**: In order to make sure that Slack is accessible in low-bandwidth environments for the community, avoid posting data-intensive content like videos directly into the channels. Instead, prioritise hosting the content on other platforms (such as YouTube), and sharing the link.
+* **Openness**: Remember that not everyone in the *The Turing Way* community is in the Slack workspace – or on every social media channel. Where possible – especially when discussing chapter ideas and other collaborations – create issues and discussions on the Github repository or post across social media channels, in order to ensure the widest reach and participation possible.
+
+In general, we encourage an approach to Slack that is as accessible as possible, for as many people as possible. Please practice kindness when you communicate with others, and be mindful of cultural, linguistic, disability, and individual differences that may affect how people communicate online.
+
+Is there anything we are missing? Please reach out to the Research Community Manager Anne Lee Steele on Slack or by email at asteele@turing.ac.uk, or to any members of the core team listed on this [Ways of Working document](https://github.com/alan-turing-institute/the-turing-way/blob/main/ways_of_working.md).
+
+## Getting started with The Turing Way
+
+* :books: If you want to dive right in to editing the book, check out a Pull Request or Issue on the [Github repository](https://github.com/alan-turing-institute/the-turing-way). Use the tags to navigate through the issues and pull requests. Ones tagged `good first issue` or `good first PR` are a great place to start.
+
+## Don't know where to start?
+
+* Feel free to send me (Anne Lee Steele) a message on Slack or email at asteele@turing.ac.uk if you have any questions or don’t know where to start. I’m the Community Manager (but just one of many leaders in this community), and here to help!
+* You can drop into [Office Hours](https://hackmd.io/@turingway/office-hours) with me every Friday, or schedule a chat on [Calendly](https://calendly.com/aleesteele/).
+* Join us at a [Collaboration Cafe](https://hackmd.io/@turingway/collaboration-cafe), which happen on a bi-monthly basis on Wednesdays to meet more members of the community, and learn more about the project.
From a804603525dcb1b87c02444e7da7dca586e3650b Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:31 +0000
Subject: [PATCH 051/142] Update source file community-handbook.md
---
book/website/community-handbook/community-handbook.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/community-handbook.md b/book/website/community-handbook/community-handbook.md
index a5453414165..a36fb966a37 100644
--- a/book/website/community-handbook/community-handbook.md
+++ b/book/website/community-handbook/community-handbook.md
@@ -41,7 +41,7 @@ Alternatively, you can contact the co-lead investigators **Malvika Sharan** by e
To stay updated with our community events, subscribe to [_The Turing Way_ calendar](https://calendar.google.com/calendar?cid=dGhldHVyaW5nd2F5QGdtYWlsLmNvbQ).
To receive monthly newsletters, [join our mailing list](https://tinyletter.com/TuringWay)
-We are also on [Twitter](https://twitter.com/turingway), follow us for daily updates.
+We are also on [X (formerly Twitter)](https://twitter.com/turingway), follow us for daily updates.
### Wondering where to start?
From 92b0e68d8a21f71ddc4a352b19d925153e6ec044 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:31 +0000
Subject: [PATCH 052/142] Update source file consistency-formatting.md
---
.../consistency/consistency-formatting.md | 17 +++++++++--------
1 file changed, 9 insertions(+), 8 deletions(-)
diff --git a/book/website/community-handbook/consistency/consistency-formatting.md b/book/website/community-handbook/consistency/consistency-formatting.md
index 481927bf94a..82e5bfb138f 100644
--- a/book/website/community-handbook/consistency/consistency-formatting.md
+++ b/book/website/community-handbook/consistency/consistency-formatting.md
@@ -23,7 +23,7 @@ _The Turing Way_ should be written in [Markdown](https://en.wikipedia.org/wiki/M
Parts of earlier chapters in _The Turing Way_ were written in `HTML`, making some of their content hard to read.
-For example, {ref}`html-to-markdown` depicts a table that was written in `HTML`.
+For example, the following figure depicts a table that was written in `HTML`.
```{figure} ../../figures/html-to-markdown.*
---
@@ -54,7 +54,7 @@ For example, [superscripts and subscripts](https://support.squarespace.com/hc/en
In addition, content like YouTube videos and tables with headers that span multiple columns or rows can be written in `HTML`.
-```{attention} A Note About Styling
+````{attention} A Note About Styling
:class: tip
_The Turing Way_ has a [book-wide stylesheet](https://github.com/the-turing-way/the-turing-way/blob/main/book/website/_static/book-stylesheet.css) that controls the look of content written in `HTML`.
@@ -62,11 +62,12 @@ If you include `HTML` in your contribution, ensure that your formatting includes
For example, if you want to add a YouTube video to your content using the `
-
```
+````
This is also described in the {ref}`Style Guide`.
@@ -138,9 +139,9 @@ This helps make _The Turing Way_ more navigable and accessible.
Some figures and images in _The Turing Way_ are embedded using Markdown syntax.
While this works, it does not allow the images to adapt to the screen size of the device the book is read from.
-Markedly Structured Text (`MyST`) is a flavour of Markdown that addresses this and enables responsive images in the _The Turing Way_.
+Markedly Structured Text (`MyST`) is a flavour of Markdown that addresses this and enables responsive images in _The Turing Way_.
-It also allows the use of captions and alternative text (ALT text), which are the invisible image descriptions that are read aloud to readers of the _The Turing Way_ who use a screen reader.
+It also allows the use of captions and alternative text (ALT text), which are the invisible image descriptions that are read aloud to readers of _The Turing Way_ who use a screen reader.
If no ALT text is provided with an image, these users will be unable to understand the purpose of the image.
When writing ALT text, remember to:
@@ -150,7 +151,7 @@ In doing so, there is no need to "announce" an image in your description (for ex
This ensures that the descriptions are easy to understand.
Please note that images included in _The Turing Way_ book should be less than 1MB.
-This allows the book load faster, especially for readers who may have slow internet connections.
+This allows the book to load faster, especially for readers who may have slow internet connections.
Please refer to the {ref}`style guide ` for examples on formatting images using `MyST` and adding ALT text to them.
When including images in your contributions, it may be better to avoid the height parameter as the wrong value could make your image appear distorted on mobile devices.
@@ -209,14 +210,14 @@ Being a citeable reference for individuals seeking to carry out reproducible dat
Although _The Turing Way_ does not follow a specific title capitalisation style, some general, non-exhaustive rules to consider include:
- Capitalise principal or important words
-- Lowercase articles, conjunctions, and prepositions (unless when these are stressed)
+- Lowercase articles, conjunctions, and prepositions (except when these are stressed)
- Capitalise the first and last words
There are helpful tools, such as [CapitalizeMyTitle](https://capitalizemytitle.com/) and [Title Case Converter](https://titlecaseconverter.com/), that can be used to title-case headers when writing your content.
Furthermore, headers in _The Turing Way_ can be run through these tools to ensure they follow title-casing conventions.
They can then be replaced within chapters and in the `_toc.yml` as appropriate.
-For example, In {ref}`mismatched-title-toc` above, **Using spreadsheets for research data** should be title-cased to **Using Spreadsheets for Research Data**.
+For example, In {ref}` the image ` above, **Using spreadsheets for research data** should be title-cased to **Using Spreadsheets for Research Data**.
Certain headers may not need to be title-cased depending on the context in which they are used.
For example, because some of the headers in this chapter make up a checklist - they do not need to be title-cased.
From d722a1f9de65267307dfb4934d070d1171e3a91d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:32 +0000
Subject: [PATCH 053/142] Update source file consistency-structure.md
---
.../community-handbook/consistency/consistency-structure.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/book/website/community-handbook/consistency/consistency-structure.md b/book/website/community-handbook/consistency/consistency-structure.md
index a7ca8e33048..a4b2a697053 100644
--- a/book/website/community-handbook/consistency/consistency-structure.md
+++ b/book/website/community-handbook/consistency/consistency-structure.md
@@ -21,7 +21,7 @@ This negatively impacts the reader's experience as they go through the book.
name: empty-toc-file
alt: An empty file that was included in the Turing Way's Table of Contents. Readers can still navigate to empty files when they are included in the table of contents.
---
-Empty files included Turing Way's Table of Contents can still be accessed by readers.
+Empty files included in _The Turing Way's_ Table of Contents can still be accessed by readers.
```
A general suggestion is to remove references to such files from the ToC and raise an issue in _The Turing Way_ Github [repo](https://github.com/the-turing-way/the-turing-way) for content to be written for those files.
@@ -100,7 +100,7 @@ The {ref}`style guide` demonstrates how to add a new reference
Soft requirements that deal with _The Turing Way's_ structure include:
(ch-consistency-structure-sr-summary)=
-### Check 1: Ensure each chapter has a good summary in their landing page
+### Check 1: Ensure each chapter has a good summary in its landing page
A chapter with a good summary gives the reader an overview of the content that follows.
Ideally, summaries should communicate the main idea of the chapter and identify any supporting detail, but be brief and precise.
@@ -116,4 +116,4 @@ Furthermore, very long content can be intimidating for other readers who may onl
Therefore, to make _The Turing Way_ easier to read, long chapters should be appropriately modularised.
When keeping chapters modular, ensure that its subchapters only talk about one aspect of the overall topic.
-For example, if a chapter on Machine Learning was to be written for _The Turing Way_, such a chapter should contain at least three subchapters that each focus Supervised Learning, Unsupervised Learning, and Reinforcement Learning.
+For example, if a chapter on Machine Learning was to be written for _The Turing Way_, such a chapter should contain at least three subchapters that each focus on Supervised Learning, Unsupervised Learning, and Reinforcement Learning.
From 7e89d185e8bf932dfade11f6cc907b96270d9222 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:33 +0000
Subject: [PATCH 054/142] Update source file contributing-workflow.md
---
.../contributing/contributing-workflow.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/book/website/community-handbook/contributing/contributing-workflow.md b/book/website/community-handbook/contributing/contributing-workflow.md
index d20c344d365..471bf0f8690 100644
--- a/book/website/community-handbook/contributing/contributing-workflow.md
+++ b/book/website/community-handbook/contributing/contributing-workflow.md
@@ -1,9 +1,9 @@
(ch-contributing-workflow)=
# Contribution Workflow
-Whether you are writing new content or reviewing existing ones, contributing to _The Turing Way_ generally encompasses the steps discussed in this section.
+Whether you are writing new content or reviewing existing content, contributing to _The Turing Way_ generally encompasses the steps discussed in this section.
You may refer to the recommendations here to ensure that you have adequately prepared your contribution for review.
-Please note that the order of these recommendations are not strict and we encourage you to follow the approach that suits you best.
+Please note that the order of these recommendations is not strict and we encourage you to follow the approach that suits you best.
(ch-contributing-workflow-template)=
## Select a template
@@ -33,9 +33,9 @@ For example, the [Version Control](https://the-turing-way.netlify.app/reproducib
book\website
│
└───reproducible-research <---- (folder for the Guide to Reproducible Research)
-│ │ reproducible-research.md <---- (Guide's Landing Page)
-│ │ vcs.md <---- (Landing page for the Version Control chapter)
-| | new-chapter <---- (Landing page for a new chapter)
+│ │ reproducible-research.md <---- (Guide's landing page)
+│ │ vcs.md <---- (landing page for the Version Control chapter)
+| | new-chapter <---- (landing page for a new chapter)
│ │
│ └───vcs (chapter folder)
│ | │ vcs-workflow.md
@@ -97,7 +97,7 @@ For example, because the [Statistical Methods Manuscript](https://the-turing-way
(ch-contributing-workflow-referencing)=
## Reference external sources appropriately
-Ensure external sources are properly referenced and included in _The Turing Way's_ centralised bibtex file as recommended in the [style guide](https://the-turing-way.netlify.app/community-handbook/style/style-citing.html)
+Ensure external sources are properly referenced and included in _The Turing Way's_ centralised BibTeX file as recommended in the [style guide](https://the-turing-way.netlify.app/community-handbook/style/style-citing.html).
(ch-contributing-workflow-glossary)=
## Update the book-wide glossary
From 6babf75f650147c7b04bbe76d2e15ebe97603ce0 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:34 +0000
Subject: [PATCH 055/142] Update source file coworking.md
---
book/website/community-handbook/coworking.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/book/website/community-handbook/coworking.md b/book/website/community-handbook/coworking.md
index debcc00a39d..9d241d1c93c 100644
--- a/book/website/community-handbook/coworking.md
+++ b/book/website/community-handbook/coworking.md
@@ -16,11 +16,11 @@ height: 300px
name: coworking
alt: An illustration of a group of people who are working together and discussing something
---
-An illustration of a group coworking. [Royalty free image from Many Pixels](https://www.manypixels.co/gallery/)
+An illustration of a group coworking. [Royalty free image from Many Pixels](https://www.manypixels.co/gallery/).
Our coworking calls provide opportunities for community members to allocate time to their desired tasks in _The Turing Way_ and get them done, partially or fully, with the support of others in the call who can help discuss their plans, share ideas or hold accountability.
```
-In this chapter, you will learn about the motivation behind holding coworking calls, techniques we use for making effective use of the allocated time, the two types of calls we host: {ref}`Collaboration Cafes ` and {ref}`Weekly Coworking` and their formats.
+In this chapter, you will learn about the motivation behind holding coworking calls, techniques we use for making effective use of the allocated time, the two types of calls we host: {ref}`Collaboration Cafes ` and {ref}`Weekly Coworking`, and their formats.
We want to make collaborative events like these as useful as possible for as many people as possible.
-Please [let the team members know](/README.md#get-in-touch) if there are other ways we can make these calls more welcoming and helpful for you.
+Please [let the team members know](https://github.com/the-turing-way/the-turing-way#get-in-touch) if there are other ways we can make these calls more welcoming and helpful for you.
From 56446a5b4c0486dc5f446af39b3a0c387479568d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:34 +0000
Subject: [PATCH 056/142] Update source file coworking-collabcafe.md
---
.../coworking/coworking-collabcafe.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/book/website/community-handbook/coworking/coworking-collabcafe.md b/book/website/community-handbook/coworking/coworking-collabcafe.md
index f8539a8ecce..874da8ea6d3 100644
--- a/book/website/community-handbook/coworking/coworking-collabcafe.md
+++ b/book/website/community-handbook/coworking/coworking-collabcafe.md
@@ -10,7 +10,7 @@ One or two members from the core team are always available on the call to suppor
## Attending an online Collaboration Cafe
The schedule for the collaboration cafe can be viewed from the [community calendar](https://calendar.google.com/calendar/embed?src=theturingway%40gmail.com&ctz=Europe%2FLondon).
-We also announce calls in our [monthly newsletters](https://tinyletter.com/TuringWay/archive), send a reminder on the [Slack channel](https://tinyurl.com/jointuringwayslack) and [Twitter](https://twitter.com/turingway).
+We also announce calls in our [monthly newsletters](https://tinyletter.com/TuringWay/archive), send a reminder on the [Slack channel](https://tinyurl.com/jointuringwayslack) and on [X (formerly Twitter)](https://twitter.com/turingway).
Though scheduled for 2 hours, we understand that for many interested participants it might be impossible to commit to the entire 2 hours on one or multiple occasions, therefore, you are welcome to join for as long as your schedule allows.
@@ -63,7 +63,7 @@ We'll run the following schedule during each Collaboration Cafe:
- Update the date for the upcoming call
- Move the notes from the previous call below the working area (that will be archived in this Notion page periodically)
- Update an icebreaker question
- - Share the notes on Slack and Twitter announcing the event
+ - Share the notes on Slack and on X announcing the event
**Want to see how we run these calls?**
@@ -77,13 +77,13 @@ Watch the video to see how Kirstie hosted the calls when it was first launched.
- Make sure that you share the Code of Conduct link and use the shared Cuckoo (or other web-based clocks)
- Create breakout rooms for people before starting the Pomodoro
- As the Pomodoro ends, close the rooms, ask for any feedback, and call for a 5 minutes break
-- Continue the repeated session for 2-3 Pomodoro, leaving the last 15-30 minutes for discussion on what people worked on.
+- Continue the repeated session for 2-3 Pomodoros, leaving the last 15-30 minutes for discussion on what people worked on
- Close the call thanking everyone, and archive the notes for the next call
#### After the Call
Please share any feedback from this call with the Community Manager of *The Turing Way*, specifically, if you have any feedback, concern or ideas for future calls.
-You are encouraged to create a Pull Request to improve this chapter that can help the future attendees and chair of the Collaboration Café.
+You are encouraged to create a Pull Request to suggest improvements to this chapter that can help future attendees and chairs of the Collaboration Café.
#### Beginning
@@ -91,7 +91,7 @@ The call begins with the team members welcoming the participants, sharing the Co
#### Breaks
-We will take short breaks after each Pomodoro to discuss what we are working on, ask questions that might help you in your next Pomodoro session, share any error or progress, and celebrate each others successes.
+We will take short breaks after each Pomodoro to discuss what we are working on, ask questions that might help you in your next Pomodoro session, share any errors or progress, and celebrate each others successes.
We will use the last 30 minutes for themed discussion, collaborative troubleshooting, or idea exchange for the project and community.
@@ -99,7 +99,7 @@ The welcome, introductions, breaks, and the open discussion will all happen in t
#### Pomodoro sessions
-Pomodoro sessions can happen either in the main zoom room in silence or in [breakout rooms](#breakout-rooms).
+Pomodoro sessions can happen either in the main Zoom room in silence or in [breakout rooms](#breakout-rooms).
We won't record the Pomodoro parts of the Collaboration Cafe, nor conversations in the breakout rooms.
You don't need to know in advance what you're going to do in those Pomodoro sessions!
There will always be someone who can help you develop a goal, or allocate a task that you can do in a couple of rounds of 20 minutes.
@@ -132,10 +132,10 @@ Here are a few example questions (so you know what to expect):
* what was your biggest achievement this week?
* when was the last time you saw a rainbow?
* what are you most excited about this year?
-* What is your favorite flavor in cake/ice-cream?
+* what is your favorite flavor in cake/ice-cream?
*Do you have another interesting question to ask others?*
-*[Get in touch](/README.md#get-in-touch) and let us know!*
+*[Get in touch](https://github.com/the-turing-way/the-turing-way#get-in-touch) and let us know!*
*We love creative suggestions!*
Here's an example from the second Collaboration Cafe in September 2019:
From 46aee8ff4bbaf1e50b8b67aed78eb25ef39453a8 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:35 +0000
Subject: [PATCH 057/142] Update source file coworking-motivation.md
---
.../coworking/coworking-motivation.md | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/book/website/community-handbook/coworking/coworking-motivation.md b/book/website/community-handbook/coworking/coworking-motivation.md
index f6a524f745f..bd0303c73e4 100644
--- a/book/website/community-handbook/coworking/coworking-motivation.md
+++ b/book/website/community-handbook/coworking/coworking-motivation.md
@@ -1,19 +1,19 @@
(ch-coworking-motivation)=
# Motivations, Background, and Techniques
-## Motivation and Background
+## Motivation and background
When _The Turing Way_ started with around 10 members located in the United Kingdom, they could work in real-time and often together in the same location.
They shared ideas, helped each other out, got huge amounts of writing, editing and reviewing done, and had lots of fun interacting with each other.
-To help the community of contributors grow beyond the core team, the in-person book dash (a shorter version of [book sprints](https://www.booksprints.net/)) were hosted to offer interested participants a similar collaborative environment with an advantage to connect with each other informally.
+To help the community of contributors grow beyond the core team, the in-person Book Dash (a shorter version of [book sprints](https://www.booksprints.net/)) were hosted to offer interested participants a similar collaborative environment with an advantage to connect with each other informally.
However, not everyone can join such in-person events.
These only work for people who can take 1-2 full days from their job-related and personal responsibilities to attend the event.
Moreover, they take a lot of time and effort in organisation and are expensive to run, especially if we want to host them frequently to allow more and more participants to experience the joy of working together.
This is where the practice of online coworking is extremely valuable for _The Turing Way_ as a community project.
-The motivation behind hosting these online calls for _The Turing Way_ community are the following:
+The motivations behind hosting these online calls for _The Turing Way_ community are the following:
1. Onboard members who are new to the project by providing a real-time orientation
2. Build personal connections between members of the community
@@ -28,7 +28,7 @@ _The Turing Way_ core team members will be on the call and point you to some sta
## Techniques
-We offer two types of coworking calls: 1-hour short calls every week to work on ongoing projects in the community, and 2-hour long bimonthly Collaboration Cafes that offers a mix of community discussion and quiet working slots.
+We offer two types of coworking calls: 1-hour short calls every week to work on ongoing projects in the community, and 2-hour long bimonthly Collaboration Cafes that offer a mix of community discussion and quiet working slots.
We encourage our members to attend for as long during these designated hours as their schedule allows, even if they can't be present during the entire call.
These calls use a combination of two techniques:
@@ -59,8 +59,8 @@ They create a cycle of 3 experiences: "habit building and progress", "social sup
### Pomodoro Technique
-The [pomodoro technique](https://en.wikipedia.org/wiki/Pomodoro_Technique) uses a timer to break down work into smaller intervals usually of 25 minutes called "Pomodoros", separated by short breaks of 5 minutes.
-Like the previous technique, the Pomodoro technique allows planning, tracking, recording, processing and visualizing the task at hand.
+The [Pomodoro Technique](https://en.wikipedia.org/wiki/Pomodoro_Technique) uses a timer to break down work into smaller intervals usually of 25 minutes called "Pomodoros", separated by short breaks of 5 minutes.
+Like the previous technique, the Pomodoro Technique allows planning, tracking, recording, processing and visualizing the task at hand.
> Pomodoro, from the Italian word for 'tomato', after the tomato-shaped kitchen timer that Francesco Cirillo used as a university student. {cite:ps}`Lifehack2020pomodoro`
@@ -68,7 +68,7 @@ The goal of this technique is to avoid procrastinating and get things done with
- identify the task
- set the Pomodoro timer (25 minutes long)
- work on the task until the timer rings
-- take a 5 minutes break
+- take a 5 minute break
- identify what would you work on next
- restart the timer and repeat the workflow
From 0f23a895f276fba60cf0884d1ab0d48b9ed0ce89 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:35 +0000
Subject: [PATCH 058/142] Update source file coworking-organisation.md
---
.../coworking/coworking-organisation.md | 36 +++++++++----------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/book/website/community-handbook/coworking/coworking-organisation.md b/book/website/community-handbook/coworking/coworking-organisation.md
index c77ea49ea04..1997c8e95fc 100644
--- a/book/website/community-handbook/coworking/coworking-organisation.md
+++ b/book/website/community-handbook/coworking/coworking-organisation.md
@@ -1,12 +1,12 @@
(ch-coworking-organisation)=
-# Organising coworking call for your community
+# Organising Coworking Calls for your Community
If you would like to set up coworking calls for your community, you can repurpose and adapt the format, templates, and materials discussed in this chapter to support your teams and communities.
-Practices described here are what we use in _The Turing Way_, but there are more ways to run such coworking calls.
-Below, I describe different aspects that you should take into consideration when planning or designing your coworking calls.
+The practices described here are what we use in _The Turing Way_, but there are more ways to run such coworking calls.
+Below, we describe different aspects that you should take into consideration when planning or designing your coworking calls.
-## Designing a format the works for you
+## Designing a format that works for you
To identify what could be the best format for your coworking calls, you need to think about the following aspects:
@@ -33,13 +33,13 @@ If you are part of a small project, you would expect the same familiar faces in
Many tasks go into organising a coworking call (discussed later).
These tasks can be taken care of by one person like a community manager, project manager, or a volunteer organiser.
However, it is always a good idea to involve more people as co-organisers so that the coworking call still happens even when the main organiser can't join for any reason.
-To avoid one person to burden themselves with "not so exciting" organisation issues, you can also decide to rotate the role within the members of your project.
+To avoid one person burdening themselves with "not so exciting" organisation issues, you can also decide to rotate the role within the members of your project.
**Size of the call**
No matter what the purpose and who the target audience of your calls are, you can decide the size of your call by managing participation by prior registration.
If you organise these calls for your project members on a mutually agreed time and with an agenda to work on specific tasks, you can expect most of them to show up.
-If you keep your call open for any of your community members join, you may end up having a different number of participants on different calls.
+If you keep your call open for any of your community members to join, you may end up having a different number of participants on different calls.
This would also mean that for some calls, there won't be anyone available to co-work with you.
It's useful to handle some sort of sign-up sheet or registration system so the organisers know who to expect on the call.
@@ -47,7 +47,7 @@ In _The Turing Way_, we use dedicated HackMD notes that can be updated before ea
**Frequency of these calls**
-Once you have identifies the purpose, target audience and size of your calls, you can decide how often you would like to host them.
+Once you have identified the purpose, target audience and size of your calls, you can decide how often you would like to host them.
If you work with the same group of people, you can host it as per your common availability and a mutually agreed time on a weekly or monthly basis.
If the expected participants of your call also work on multiple projects, you might consider regularly hosting it on the same day and time each week or each month.
@@ -58,7 +58,7 @@ This will also reduce the extra work of coordinating the common availability eve
Based on the resources available to you, you might have to fine-tune other aspects of your call.
For example:
-- Shared calendar: If there is a calendar that are updated with the coworking calls schedule, people can subscribe to them and indicate their availability.
+- Shared calendar: If there is a calendar that is updated with the coworking calls schedule, people can subscribe to them and indicate their availability.
- Communication platforms: software like Zoom can allow you to connect with many people at the same time. However, you will need a paid subscription (pro account) to control who joins your call (by activating waiting room to avoid Zoom bombing), manage breakout rooms (to allow multiple small groups and discussions) or host longer calls (>40 minutes).
- Chat system: If you have a group Slack or Gitter channel, information can be exchanged with everyone, including those who can not join the calls but want to offer suggestions or carry out related tasks asynchronously but in coordination with the group.
This also allows people to keep each other informed of any last-minute changes such as updated links for joining calls, correct notes, or cancellation of calls.
@@ -72,16 +72,16 @@ As the organisers of the event, you will be required to:
The following aspects will require you to make choices in regards of what tools you will use.
-- maintaining shared notes: few options are [Etherpad](https://etherpad.org/), [HackMD](https://hackmd.io/), [GitHub](https://github.com/), [Google doc](https://en.wikipedia.org/wiki/Google_Docs)
-- managing registration: few options are via shared notes, [Zoom](https://zoom.us), [Eventbrite](https://www.eventbrite.com/), [Google Form](https://en.wikipedia.org/wiki/Google_Forms)
-- hosting the calls: few options are [Zoom](https://zoom.us), [Google Hangout](https://en.wikipedia.org/wiki/Google_Hangouts), [Skype](https://www.skype.com/en/), [Jisti](https://meet.jit.si/)
-- facilitating chats: few options are [Slack](https://slack.com/), [Gitter](https://gitter.im/), other [web-based or phone applications](https://www.makeuseof.com/tag/messaging-apps-phone-computer/)
-- sharing timers: few options are [cuckoo.team](https://cuckoo.team/), [vclock](https://vclock.com/timer/) or other web-based timers
-- finding a common availability: few options are [Doodle](https://doodle.com/poll/), [when2meet.com](https://www.when2meet.com/), or other [meeting schedule apps](https://zapier.com/blog/best-meeting-scheduler-apps/)
+- maintaining shared notes: a few options are [Etherpad](https://etherpad.org/), [HackMD](https://hackmd.io/), [GitHub](https://github.com/), [Google doc](https://en.wikipedia.org/wiki/Google_Docs)
+- managing registration: a few options are via shared notes, [Zoom](https://zoom.us), [Eventbrite](https://www.eventbrite.com/), [Google Form](https://en.wikipedia.org/wiki/Google_Forms)
+- hosting the calls: a few options are [Zoom](https://zoom.us), [Google Hangout](https://en.wikipedia.org/wiki/Google_Hangouts), [Skype](https://www.skype.com/en/), [Jitsi](https://meet.jit.si/)
+- facilitating chats: a few options are [Slack](https://slack.com/), [Gitter](https://gitter.im/), other [web-based or phone applications](https://www.makeuseof.com/tag/messaging-apps-phone-computer/)
+- sharing timers: a few options are [cuckoo.team](https://cuckoo.team/), [vclock](https://vclock.com/timer/) or other web-based timers
+- finding a common availability: a few options are [Doodle](https://doodle.com/poll/), [when2meet.com](https://www.when2meet.com/), or other [meeting schedule apps](https://zapier.com/blog/best-meeting-scheduler-apps/)
**2. Plan and host the calls**
-As discussed earlier, you will need to agree upon dates and time with people who would like to participate in coworking calls.
+As discussed earlier, you will need to agree upon dates and a time with people who would like to participate in coworking calls.
Your calls could be organised on a weekly or monthly basis that consistently take place on a certain day and time periodically, or it could be organised once in a while by finding a common availability.
Once you have found a schedule (date, time and frequency), the following tasks will go into planning them:
@@ -90,7 +90,7 @@ Once you have found a schedule (date, time and frequency), the following tasks w
It is particularly crucial to use meeting links like [arewemeetingyet](https://arewemeetingyet.com/) for communicating these schedules for members from different countries so that they can see the time in their time zones.
For hosting these calls, you can reuse and adapt the agenda, techniques and templates described in the earlier chapters.
-You main tasks as a host will be to:
+Your main tasks as a host will be to:
- provide adequate support to the participants so that they can make the best of their time.
In _The Turing Way_ coworking calls, we find it useful to use breakout rooms when there are many people working in small groups or if some people need more discussions, while others want to quietly work on their tasks.
- facilitate shared notes with participants before, during and after the call, so that they can keep track of useful resources or ideas they discuss during the coworking call.
@@ -99,13 +99,13 @@ In _The Turing Way_ coworking calls, we find it useful to use breakout rooms whe
Though discussed last, this should be your highest priority.
-You should design these calls with an intention to make everyone feel welcome, involved and safe.
+You should design these calls with the intention to make everyone feel welcome, involved and safe.
It's highly recommended to choose a Code of Conduct and put reporting guideline in place to share with everyone in advance.
See this minimal [CoC from Contributor Covenant](https://www.contributor-covenant.org/) and an expanded version of {ref}`The Turing Way CoC`.
Additionally, you should also communicate the basic etiquettes, such as muting microphones when not speaking or not interrupting others when working in a Pomodoro session unless necessary.
It is useful to let everyone know who they can contact if they need help in troubleshooting during the call or need more time to discuss their ideas.
-Create an agenda that states clearly what is expected of them, such as if they should bring their tasks and questions in the call or communicate them beforehand.
+Create an agenda that states clearly what is expected of them, such as if they should bring their tasks and questions to the call or communicate them beforehand.
In _The Turing Way_, we have dedicated slots for both group discussions and quiet working.
From 401dfaaf3601bf44cb13ad027d8465b6c63677c4 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:36 +0000
Subject: [PATCH 059/142] Update source file coworking-weekly.md
---
.../coworking/coworking-weekly.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/book/website/community-handbook/coworking/coworking-weekly.md b/book/website/community-handbook/coworking/coworking-weekly.md
index 70ea571e100..9f73afdddbb 100644
--- a/book/website/community-handbook/coworking/coworking-weekly.md
+++ b/book/website/community-handbook/coworking/coworking-weekly.md
@@ -14,10 +14,10 @@ These calls also provide opportunities to clarify doubts about the project, get
## Attending an online coworking call
-The schedule for these coworking calls is updated weekly [community calendar](https://calendar.google.com/calendar/embed?src=theturingway%40gmail.com&ctz=Europe%2FLondon).
+The schedule for these coworking calls is updated weekly in the [community calendar](https://calendar.google.com/calendar/embed?src=theturingway%40gmail.com&ctz=Europe%2FLondon).
We announce these in our [monthly newsletters](https://tinyletter.com/TuringWay/archive) and send a reminder every Monday on the [Slack channel](https://tinyurl.com/jointuringwayslack).
-Though scheduled for 1 hour, you are welcome to join for shorter period as your schedule allows, however, please let the host of the call know so that they know who to expect on the call.
+Though scheduled for 1 hour, you are welcome to join for shorter periods as your schedule allows, however, please let the host of the call know so that they know who to expect on the call.
If you are interested in coworking with one of the team members on a day that is not listed on the schedule, please contact them on Slack or by email so that they can find a common slot to work with you.
### Resource used for the call
@@ -29,7 +29,7 @@ The resource requirement for these calls is also very similar to the Collaborati
3. An online Pomodoro clock: [https://cuckoo.team/TW-coworking](https://cuckoo.team/TW-coworking)
We don't record these calls.
-We also don't create {ref}`breakout rooms` unless there are multiple people working on same things.
+We also don't create {ref}`breakout rooms` unless there are multiple people working on the same thing.
### Format of the call
@@ -55,13 +55,13 @@ Please update the document each month using the following steps:
- [Update the HackMD](https://hackmd.io/@turingway/coworking-call) each month by adding dates for the weekly calls
- Move the notes from the previous call below the template area (that will be archived in this Notion page periodically)
-- Share the notes on Slack and Twitter announcing the dates
+- Share the notes on Slack and X (formerly Twitter) announcing the dates
- Use the notes during the call to share information as you chair the call
- Make sure that you share the Code of Conduct link and use the shared Cuckoo (or other web-based clocks)
- Create breakout rooms for people before starting the Pomodoro sessions - when needed
- As the first Pomodoro session ends, close any breakout rooms, ask for feedback, and then restart the second Pomodoro session
- The call is scheduled for 60 minutes, and hence can accommodate up to 2 Pomodoro sessions
-- Close the call thanking everyone, and arhieve the notes for the next call
+- Close the call thanking everyone, and archive the notes for the next call
#### Beginning
@@ -71,13 +71,13 @@ The call begins with the team members welcoming the participants, sharing the Co
The session chair will start the [timer](https://cuckoo.team/TW-coworking) to keep track of the Pomodoro sessions.
If everyone plans to work on independent tasks, we will remain in the main room and work silently.
-For any discussion or collaborative task that two people of the call are working on, we will create [breakout rooms](#breakout-rooms) for them.
+For any discussion or collaborative task that two people of the call are working on, we will create [breakout rooms][ch-coworking-collabcafe-breakout] for them.
-If there are new members on the call, one of the members (usually host of the call) will take the new member to a breakout room to show around the project repository and share some tips for getting started.
+If there are new members on the call, one of the members (usually host of the call) will take the new member to a breakout room to show them around the project repository and share some tips for getting started.
#### Breaks
-We will take short breaks after each Pomodoro to reflect on what we could get done, troubleshoot any error that any attendee might have come across, verbalise our progress and celebrate small successes.
+We will take short breaks after each Pomodoro to reflect on what we could get done, troubleshoot any errors that any attendee might have come across, verbalise our progress and celebrate small successes.
#### If joining this call later
From db5578df5757e535ae91b0fa616e3fcb0cc3baf4 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:36 +0000
Subject: [PATCH 060/142] Update source file fireside-chat.md
---
book/website/community-handbook/fireside-chat.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/website/community-handbook/fireside-chat.md b/book/website/community-handbook/fireside-chat.md
index d264a4b9c87..a5f10340501 100644
--- a/book/website/community-handbook/fireside-chat.md
+++ b/book/website/community-handbook/fireside-chat.md
@@ -35,12 +35,12 @@ However, most of these communities operate independently of other initiatives, e
This often results in scientific outputs that most users can find, but not access, or build upon in their local contexts.
Open discussions and spaces for collaborations can contribute to individual benefit, team efforts as well as the overall sustainability of the open science ecosystem {cite}`Sharan2021reimagine`.
-*The Turing way* Fireside Chat series will facilitate discussions on topics of broader interest, create shared spaces for cross-community collaborations and build opportunities for exchanging common experiences and resources.
+*The Turing Way* Fireside Chat series will facilitate discussions on topics of broader interest, create shared spaces for cross-community collaborations and build opportunities for exchanging common experiences and resources.
## Scope
The Fireside Chat series is hosted online on topics of interest within *The Turing Way* community as well as members across other mission-aligned projects such as Open Life Science, The Carpentries, Open Post Academics, Open Science Community in Saudi Arabia, Wikimedia, Frictionless Data, Talarify in South Africa and MetaDocencia (some of our collaborators so far).
-We will continue to collaborate with other communities working in participatory, open research and citizen space to organise future events on topics that they are working on.
+We will continue to collaborate with other communities working in participatory, open research and citizen spaces to organise future events on topics that they are working on.
Although *The Turing Way* hosts these calls in English, we encourage our collaborative projects to consider hosting a future event in their time zones, in their primary languages and on topics relevant to their local contexts.
@@ -59,7 +59,7 @@ Suggestions of topics for the future Fireside chat include:
### Frequency and Duration
These calls are hosted every month on the third or fourth Friday as per the common availability of all speakers.
-Recommended duration is 60 to 90 minutes which are recorded to post online for people who can't attend these calls in real-time.
+The recommended duration is 60 to 90 minutes which are recorded to post online for people who can't attend these calls in real-time.
Hosts can consider allocating a part of the call for open discussions with participants, however, this part doesn't need to be recorded to allow maximum participation by attendees who may otherwise not engage.
The schedule is decided based on the availability of individuals invited as speakers/panellists.
@@ -68,7 +68,7 @@ The schedule is decided based on the availability of individuals invited as spea
- **GitHub checklist for organisers and speakers**: we have a checklist for planning the Fireside Chat as an [issue template](https://github.com/the-turing-way/the-turing-way/issues/new/choose). For each iteration, event hosts will create a new issue to allow other participants to follow along with the planning process.
- **Eventbrite pages**: Registrations are handled via [*The Turing Way* Eventbrite page](https://www.eventbrite.co.uk/o/the-turing-way-18600928389). The event is free to attend and recordings are shared with all registered participants after the event.
- **Zoom**: We host Fireside events online using [Zoom](https://zoom.us/) (with live transcription), however, the platform for the participants can change based on the preference of the majority of speakers.
-- **Online promotion**: Announcements are shared on *The Turing Way* [Twitter](https://twitter.com/turingway), [Slack workspace](https://tinyurl.com/jointuringwayslack) and [monthly newsletters](https://tinyletter.com/TuringWay), which are then cross-posted by other communities in their network.
+- **Online promotion**: Announcements are shared on *The Turing Way* [X (formerly Twitter)](https://twitter.com/turingway), [Slack workspace](https://tinyurl.com/jointuringwayslack) and [monthly newsletters](https://tinyletter.com/TuringWay), which are then cross-posted by other communities in their network.
- **Shared Documents**: We currently use Etherpad by Software Freedom Conservancy to enable shared note-taking during the event. Refer to this for example - https://pad.sfconservancy.org/p/ttw-fireside-chat-mar2022.
- **Template** is provided as a subchapter: {ref}`ch-template-fireside-chat`.
- **Overview of all Fireside Chats** are currently shared via HackMD: https://hackmd.io/@turingway/fireside-chats.
From 07d1ea1d78f89147ca02f03147e9e297d96527d1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:37 +0000
Subject: [PATCH 061/142] Update source file fireside-chat-checklist.md
---
.../fireside-chat/fireside-chat-checklist.md | 34 +++++++++----------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/book/website/community-handbook/fireside-chat/fireside-chat-checklist.md b/book/website/community-handbook/fireside-chat/fireside-chat-checklist.md
index 5b2fd3d5b29..5590ca8f7c1 100644
--- a/book/website/community-handbook/fireside-chat/fireside-chat-checklist.md
+++ b/book/website/community-handbook/fireside-chat/fireside-chat-checklist.md
@@ -5,42 +5,42 @@
## Before the Event
- Create a planning issue on GitHub using the [issue template - Fireside Chat Checklist](https://github.com/the-turing-way/the-turing-way/issues/new/choose)
-- A Turing Way team member (Community Manager or Research Project Manager) will create a Zoom link with a waiting room and live transcription enabled. They will also open the call on the day of the event, and give 'co-host rights' to all facilitators to allow them to manage Zoom participants and chats.
-- Identify an overarching theme that we share with a different community -- Fireside Chat is intended to promote cross-community collaboration
+- A Turing Way team member (Community Manager or Research Project Manager) will create a Zoom link with a waiting room and live transcription enabled. They will also open the call on the day of the event, and give 'co-host rights' to all facilitators to allow them to manage Zoom participants and chats
+- Identify an overarching theme that we share with a different community -- Fireside Chats are intended to promote cross-community collaboration
- Reach out to a community/project/organisation representative who can co-facilitate the event with a core team member in *The Turing Way*
- Set up an internal shared document for discussions and notes (use [this Google doc template](https://docs.google.com/document/d/1X_NfRkkH6p47yRgpd6xlw8yrvo6jIsbF_mV0BinjcaQ/edit?usp=sharing))
- Discuss what the co-hosts might want to highlight at this Fireside Chat (note: these discussions don't necessarily need to identify a solution - but should recognise shared themes, challenges, and spaces for research communities)
- Identify speakers from the community and invite them
-- Create a private Slack Channels with all speakers and hosts and discuss some overarching topics they are interested in sharing
+- Create a private Slack Channel with all speakers and hosts and discuss some overarching topics they are interested in sharing
- Ask for the bio and image of speakers, and their permission to record the session
- Schedule the first check-in 4-5 weeks in advance to surface some common themes, helping plan the title and questions
-- Decide on a common date and send placeholder calendar invite blocking their calendar for the event (15 mins pre-event tech-check/Green room, 60 minutes live and 15-30 minutes unrecorded discussion with the audience)
-- Create an Eventbrite page in *The Turing Way* account - refer to [this page for example](https://www.eventbrite.co.uk/e/navigating-growth-and-scale-to-sustain-open-communities-tickets-360328802147) (you can copy and edit)
+- Decide on a common date and send a placeholder calendar invitation blocking their calendar for the event (15 mins pre-event tech-check/Green room, 60 minutes live and 15-30 minutes unrecorded discussion with the audience)
+- Create an Eventbrite page in *The Turing Way* account - refer to [this page for an example](https://www.eventbrite.co.uk/e/navigating-growth-and-scale-to-sustain-open-communities-tickets-360328802147) (you can copy and edit)
- Set up the Etherpad using the template provided here: https://hackmd.io/@turingway/fireside-chats (browse [this example](https://pad.sfconservancy.org/p/ttw-fireside-chat-mar2022))
-- Create a paragraph to add to the Eventbrite page along with the speakers' and hosts' bio
+- Create a paragraph to add to the Eventbrite page along with the speakers' and hosts' bios
- Create a flyer to share on social media using [this template](https://docs.google.com/presentation/d/1Fx2WcVvGX6dM3z74VDQp_UD8edKp6Phl/edit?usp=sharing&ouid=102682705838770934280&rtpof=true&sd=true)
-- Coordinate on Slack with the speakers if they are happy with the announcements and if their info is correct
-- Announce at least 3-4 weeks in advance on Slack, Newsletter, Twitter and different talks
-- Add information to the Intro hackmd: https://hackmd.io/@turingway/demo-intro
+- Coordinate on Slack with the speakers to check if they are happy with the announcements and if their info is correct
+- Announce at least 3-4 weeks in advance on Slack, Newsletter, X (formerly Twitter) and in different talks
+- Add information to the Intro HackMD: https://hackmd.io/@turingway/demo-intro
- Hosts will define an agenda and questions for the session - hosts will also allocate some questions for each other to speak on
- Set another check-in at least 2 weeks in advance to touch base and discuss the plans and questions with the speakers - assign 1-2 questions for each speaker to begin
-- Plan with cohost who will ask which question, how you will time keep, what channel you will use to ask questions to each other privately, who will monitor the chat (maybe ask someone outside this group to help with note taking and chat monitoring)
-- Update the calendar invite with Zoom, Etherpad and Eventbrite -- encouraging them to share the Eventbrite page in their network
+- Plan with your cohost who will ask which question, how you will time keep, what channel you will use to ask questions to each other privately, who will monitor the chat (maybe ask someone outside this group to help with note taking and chat monitoring)
+- Update the calendar invitation with Zoom, Etherpad and Eventbrite -- encouraging them to share the Eventbrite page in their network
- Identify someone from the community who can do the introduction of *The Turing Way*, Code of Conduct (CoC) reminder and pass it to the speakers
## During the session
- Open the Zoom call 15 minutes in advance (keep the waiting room of Zoom enabled)
-- Test if speakers' microphone, camera and internet work alright - help troubleshoot any tech challenge
+- Test if speakers' microphones, cameras and internet work alright - help troubleshoot any tech challenges
- Let participants in right on time
-- Welcome them and share Etherpad
+- Welcome them and share the Etherpad
- Remind them that the call will be recorded and that participants can use chat (but may not have the chance to speak during the 60 minutes live)
- Start recording (on Zoom Cloud) and enable transcription
- At 5 minutes past, as people join, the person designated to welcome them will introduce *The Turing Way*, CoC, and Etherpad information and Present the topic
- Hosts then introduce themselves and pose an opening question allowing all speakers including the co-host to share their positions on the topic in ~2 minutes
-- As planned in the agenda, hosts ask the question to the specific speaker, follow up response from the other speaker is invited
+- As planned in the agenda, hosts ask the question to the specific speaker, a follow up response from the other speaker is invited
- Speakers will make sure that everyone on the panel has had an equal chance to discuss and share their opinions
-- Any question from the chat is copied over the Etherpad, in the last 10 minutes publically posed question can be asked
+- Any question from the chat is copied over to the Etherpad, in the last 10 minutes publicly posed questions can be asked
- The recorded session finishes with a short closing arguments from each speaker and host
- After the recorded part of the discussion (60-75 minutes), all participants are reminded of the next stage of unrecorded discussion informally with the speakers
- Hosts close the call after 90 minutes of the session (with 15-30 minutes unrecorded discussion)
@@ -50,10 +50,10 @@
- Send a thank you email to the speakers (within 1 day)
- Archive session notes by copying them from Etherpad to the internal planning document
- Download the video from Zoom and edit the live transcription (proofread for accuracy) -- invite volunteer support as needed
-- Upload the video on *The Turing Way* youtube - label and annotate well, and add the flyer as the video's front page
+- Upload the video on *The Turing Way* YouTube - label and annotate well, and add the flyer as the video's front page
- Share the published videos with the speakers
- Summarise the session to add to *The Turing Way* -- invite someone from the community who could help with that
-- Promote the video via Slack, Newsletter, Twitter
+- Promote the video via Slack, Newsletter, X
- Send a thank you email to the Eventbrite participants sharing the video and inviting any ideas and suggestions for improvement via a standard feedback form
- Update the book chapter and templates if needed
- Add speakers to the contributors table on GitHub repo using `all-contributions bot` for presentation
From c8c73f648d38ea8ed31daeb0bcd996ef9d8d997c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:38 +0000
Subject: [PATCH 062/142] Update source file fireside-chat-roles.md
---
.../fireside-chat/fireside-chat-roles.md | 32 +++++++++----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/book/website/community-handbook/fireside-chat/fireside-chat-roles.md b/book/website/community-handbook/fireside-chat/fireside-chat-roles.md
index ba938912326..715fc5e944c 100644
--- a/book/website/community-handbook/fireside-chat/fireside-chat-roles.md
+++ b/book/website/community-handbook/fireside-chat/fireside-chat-roles.md
@@ -3,7 +3,7 @@
# Fireside Chat Roles and Responsibilities
(ch-fireside-chat-roles-chair)=
-## Chair - Opens the Session
+## Chair - opens the session
One of *The Turing Way* team members will open the panel, welcoming the audience, introducing *The Turing Way* and the Fireside Chat, and setting the norm (Code of Conduct [CoC], Etherpad, chat, question process). They’ll thank the co-hosts and pass the ‘mic’ to them.
Here is a [suggested script](https://docs.google.com/document/d/1U41vfHQ0Ks0HfgE8mreaXhrRsfviKBr9Cr3V4DJ644c/edit).
@@ -13,11 +13,11 @@ Norm setting here means, making sure that the opening script includes these deta
* We co-design the session with the co-hosts -- they are also the speaker in the session and we don’t have the moderator vs speaker differentiation.
* We try to bring different views, perspectives and backgrounds through the speakers. We very much welcome suggestions and nominations for speakers.
* We use Etherpad to share the format, invite everyone to share their notes and resources and take them back with them after the event.
-* Engaging via chat is optional, if you get distracted by the chats, please disable the notification.
+* Engaging via chat is optional, if you get distracted by the chats, please disable chat notifications.
* You can share your question via Etherpad or Zoom chat. Co-hosts will try to address them in the last part of the discussion. If we don’t have the time to address them live, we will make sure to respond via Etherpad.
(ch-fireside-chat-roles-hosts)=
-## Co-hosts - Facilitate the Session
+## Co-hosts - facilitate the session
Co-hosts are invited to co-design the event with one of *The Turing Way* team members.
They enable a discussion that does not look for answers or solutions but creates shared opportunities for members from different communities to explore a topic or challenge from their contexts.
@@ -33,9 +33,9 @@ If there are solutions available, that is great! But that is not the goal. The h
* Decide on the speakers - they are invited and details are added on the Eventbrite page and other promotional material.
* If they already know the suggested speaker, we will appreciate it if they can send the invitation and get confirmation using an [email draft](https://docs.google.com/document/d/12VoVexsXXBx25SnAU4mayPw5un-v936g9Ux61DLjGzo/edit).
* Host 30 mins calls with the speakers before the event to identify what they would like to speak about.
-* Frame questions based on their discussions with the speakers, and invite speakers to help finalise the question (using Slack and the planning document).
+* Frame questions based on their discussions with the speakers, and invite speakers to help finalise the questions (using Slack and the planning document).
* Considering the flow of the discussion, decide on the order of the questions that will be asked.
- * Each co-host should have equal opportunity to get the ‘stage time’
+ * Each co-host should have equal opportunity to get ‘stage time’.
* They should agree on which questions they will pose to guide the discussion.
* They should pose 1 question to each speaker who takes a lead on responding. 1-2 follow-up responses can be invited from other speakers.
* Make sure that the speakers know in what order they will be speaking, and what questions will be asked.
@@ -44,7 +44,7 @@ If there are solutions available, that is great! But that is not the goal. The h
* Finalise a question for the closing statement (30-60 seconds take away from each speaker)
(ch-fireside-chat-roles-speakers)=
-## Speakers - Guide the Discussion
+## Speakers - guide the discussion
We host 5-6 speakers in the panel, which includes the facilitators.
It is important to note that Fireside Chats don't have the traditional role of facilitators versus speakers.
@@ -56,15 +56,15 @@ Facilitators are invited based on their experience on the topic and they also re
* They will be coordinating with the co-host to finalise the specific question posed to them, and if they would like, they can suggest another question for the other panellists.
* They will have access to the internal planning documents where they can find all information they need, as well as have opportunities to give feedback by directly collaborating on the Google document.
* They should check what in addition to questions posed to them, questions they would like to respond to as a follow-up discussion.
-* Join Zoom at least 5-10 minutes before the event to test their system (microphone, camera, internet, and access to document used for the session)
+* Join Zoom at least 5-10 minutes before the event to test their system (microphone, camera, internet, and access to the document used for the session).
* It is important that all speakers get the same ‘stage time’. (If you are the speaker -- please take this space to share your thoughts if you are generally not the one speaking out, and if you generally tend to speak more, please intentionally create space for others to speak).
-* We suggest not engaging in the Zoom chat to avoid getting distracted. The co-hosts will keep track of questions being asked there and share on the Etherpad, as well as pose to the panel if time allows.
+* We suggest not engaging in the Zoom chat to avoid getting distracted. The co-hosts will keep track of questions being asked there and share them on the Etherpad, as well as posing them to the panel if time allows.
* If we can’t cover all the audience questions, we encourage speakers to take 5 minutes after the event to respond on Etherpad.
* We will upload the video on YouTube, so if there are any parts of the discussion speakers would rather not have shared there, they should let *The Turing Way* team know.
* If the speakers have any written scripts while preparing for this panel (such as for the opening and closing statements), we request them to share those with *The Turing Way* team to help with their video transcription review work.
(ch-fireside-chat-roles-team)=
-### *The Turing Way* Team - Supports the Event
+### *The Turing Way* team - supports the event
* They will co-host the event with a project/organisation partner, who they will invite at least 6 weeks in advance.
* They will invite the co-host to join a private Slack channel and set up the internal planning document to coordinate with them.
@@ -78,22 +78,22 @@ They will make sure that there is someone delegated to contact the speaker using
* They will help set up the Eventbrite, Etherpad, Zoom and Flyer for online sharing -- inviting feedback and edits from the co-hosts and speakers.
* They will support co-hosts in finalising and communicating the questions and format for the panel.
* They will send calendar invites for the event with a link for joining the call and share the speaker release form via email before the event.
-* On the day of the event, a team member will open the call, welcome participants and monitor chat and Etherpad.
-* They will upload the video on YouTube:
+* On the day of the event, a team member will open the call, welcome participants and monitor the chat and Etherpad.
+* They will upload the video to YouTube:
* *The Turing Way* team will invite volunteers and/or speakers to help review the uploaded transcription for correctness.
* They will send a “thank you email” to all the attendees via Eventbrite sharing the link to the YouTube video.
-* They will thank the speakers, and make sure that the signed speaker’s release form has been obtained.
+* They will thank the speakers, and make sure that the signed speakers' release forms have been obtained.
(ch-fireside-chat-roles-agenda)=
-## Event Agenda
+## Event agenda
Fireside Chats follow this rough agenda:
* The co-hosts will introduce the topic and the panel. The invited co-host will also introduce their organisation/community as co-organisers.
* Each speaker will give a 2-minute pitch covering their interests, experiences, concerns and insights related to the event's topic.
-* Session hosts will state the question and invite responses from 1-2 speakers (the questions can be agreed upon in advanced) - there might be follow-up question based on the response that we may not have discussed in advance
+* Session hosts will state the question and invite responses from 1-2 speakers (the questions can be agreed upon in advanced) - there might be follow-up question based on the response that we may not have discussed in advance.
* Hosts will make sure that all speakers have had the chance to speak (by responding to different questions) and express their thoughts or share resources from their work.
* If time permits, co-hosts will take questions from the audience and speakers will be invited to address them.
-They will also invite attendees to use Zoom chat and Etherpad notes to share their thoughts.
-* The session will conclude with a final 1-minute pitch as the take-home message by each speaker.
+They will also invite attendees to use Zoom chat and the Etherpad notes to share their thoughts.
+* The session will conclude with a final 1-minute pitch as the take-home message from each speaker.
From d3055ebcafeea3eb2f563a527f556dfaa6b224cc Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:39 +0000
Subject: [PATCH 063/142] Update source file infrastructure.md
---
book/website/community-handbook/infrastructure.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/book/website/community-handbook/infrastructure.md b/book/website/community-handbook/infrastructure.md
index 8c6607302d8..9ab21aa45c3 100644
--- a/book/website/community-handbook/infrastructure.md
+++ b/book/website/community-handbook/infrastructure.md
@@ -10,14 +10,14 @@ Some examples include:
- Instructions to build the site from the source files, both {ref}`locally` and [for deployment](https://github.com/the-turing-way/the-turing-way/blob/main/netlify.toml)
- Continuous integration {term}`Continuous Integration` tasks to look for problems in the source
-- Redirect rules to help site navigation and avoid '404 Not Found'
-- Hosting {term}`Hosting` and {term}`DNS`
+- Redirect rules to help site navigation and avoid '404 Not Found' errors
+- {term}`Hosting` and {term}`DNS`
Some of this is controlled by data in the repository itself.
-For example, quality control process to ensure the book will build and help maintain accessibility standards are part of the {ref}`Continuous Integration` process and described in the [.github/workflows/](https://github.com/the-turing-way/the-turing-way/tree/main/.github/workflows) directory.
+For example, quality control processes to ensure the book will build and help maintain accessibility standards are part of the {ref}`Continuous Integration` process and described in the [.github/workflows/](https://github.com/the-turing-way/the-turing-way/tree/main/.github/workflows) directory.
-Some aspects may not declared in the repository.
+Some aspects may not be declared in the repository.
For example, hosting is provided by Netlify which holds some of its own configuration.
-This section of the book describes infrastructure that The Turing Way uses.
+This section of the book describes the infrastructure that _The Turing Way_ uses.
The aim is to demystify how things work, ensure that the infrastructure is described openly, and to help people contribute to infrastructure.
From 4982f1d07c38fb2394f76de92579add0e1cc97e8 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:39 +0000
Subject: [PATCH 064/142] Update source file infrastructure-contributors.md
---
.../infrastructure/infrastructure-contributors.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/website/community-handbook/infrastructure/infrastructure-contributors.md b/book/website/community-handbook/infrastructure/infrastructure-contributors.md
index 94096027e04..efbaa2b5360 100644
--- a/book/website/community-handbook/infrastructure/infrastructure-contributors.md
+++ b/book/website/community-handbook/infrastructure/infrastructure-contributors.md
@@ -10,7 +10,7 @@ This page documents how these sources are combined to create the {ref}`Record of
## Personal Highlights
-The {ref}`Personal Highlight section` is taken directly from [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) in the root of the repository.
+The {ref}`Personal Highlights section` is taken directly from [`contributors.md`](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md) in the root of the repository.
This is inserted into [`contributors-record.md`](https://github.com/the-turing-way/the-turing-way/blob/main/book/website/afterword/contributors-record.md) verbatim using the [`include` docutils directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment).
To modify this section you would change `contributors.md` and rebuild the book.
@@ -19,11 +19,11 @@ To modify this section you would change `contributors.md` and rebuild the book.
The {ref}`All Contributors section` displays the same [all contributors](https://allcontributors.org/docs/en/overview) table as [`README.md`](https://github.com/the-turing-way/the-turing-way/blob/main/README.md).
-The information to build this table is contained in [`.all-contributors.rc`](https://github.com/the-turing-way/the-turing-way/blob/main/.all-contributorsrc), the configuration file for all contributors.
+The information to build this table is contained in [`.all-contributorsrc`](https://github.com/the-turing-way/the-turing-way/blob/main/.all-contributorsrc), the configuration file for all contributors.
This JSON file controls the appearance of the table and also specifies where to write the all contributors table in the `"files"` list.
Each time the all contributors bot or CLI is run the table will be written to files in the `"files"` list.
-The table is inserted as HTML between the following sets of tags
+The table is inserted as HTML between the following sets of tags:
```Markdown
@@ -44,4 +44,4 @@ Manual changes to the contributors list, such as adding a contributor or regener
## Collaborating Organisations and Projects
-The {ref}`Collaborating Organisation and Projects section` is written directly in `contributors-record.md`.
+The description of the {ref}`Collaborating Organisation and Projects` should be directly written in `collaborarators.md` file in the 'Afterword' of the book.
From b29fc1cbf192949d9c86cf8f00b1da821408231d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:40 +0000
Subject: [PATCH 065/142] Update source file
infrastructure-external-link-check.md
---
.../infrastructure/infrastructure-external-link-check.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/community-handbook/infrastructure/infrastructure-external-link-check.md b/book/website/community-handbook/infrastructure/infrastructure-external-link-check.md
index 90bd405dd57..7322254fc68 100644
--- a/book/website/community-handbook/infrastructure/infrastructure-external-link-check.md
+++ b/book/website/community-handbook/infrastructure/infrastructure-external-link-check.md
@@ -4,7 +4,7 @@ The external link check tests if links between pages of _The Turing Way_ and oth
This is a useful tool which helps us ensure that when users click a link they are brought to a working page.
There is a [GitHub workflow](https://github.com/the-turing-way/the-turing-way/blob/HEAD/.github/workflows/external_link_check.yml) which regularly tests external links in the book and posts a list of broken links to an [issue](https://github.com/the-turing-way/the-turing-way/issues/3171).
-This section explains the processes which updates the broken links issue.
+This section explains the process which updates the broken links issue.
## Workflow
@@ -27,7 +27,7 @@ An example configuration file with explanations can be found in [the Lychee docu
The configuration file can be used to improve the usefulness of the broken links issue.
In particular, it is possible to exclude domains which are known to produce false negatives using the [`--exclude` argument](https://lychee.cli.rs/#/recipes/filtering-links) on the command line or the equivalent `exclude` key in the [configuration file](https://lychee.cli.rs/#/usage/config).
-Lychee produces a report of broken links and save this to a Markdown file.
+Lychee produces a report of broken links and saves this to a Markdown file.
The workflow then concatenates this report with an [issue header](https://github.com/the-turing-way/the-turing-way/blob/main/.github/workflows/resources/external_link_check_header.md) and updates the broken links issue.
## Issue
From f0ed7a2c68aa070d57f833aa8c8ac0fba70920c6 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:40 +0000
Subject: [PATCH 066/142] Update source file local-build.md
---
.../website/community-handbook/local-build.md | 127 ++++++++++++++----
1 file changed, 101 insertions(+), 26 deletions(-)
diff --git a/book/website/community-handbook/local-build.md b/book/website/community-handbook/local-build.md
index d7a29518f00..7b7c24b9360 100644
--- a/book/website/community-handbook/local-build.md
+++ b/book/website/community-handbook/local-build.md
@@ -1,11 +1,12 @@
(ch-local-build)=
-# Build the Turing Way book locally
+# Build the Turing Way Book Locally
## But why build locally?
-It's always handy to be able to preview any changes you have been working on as you go - you can be confident that changes you have made are accurate and as intended.
-A nice way to do this is to use the underlying [Jupyter Book](https://jupyterbook.org/en/stable/intro.html tool to build the book locally.
-This is useful because it allows you to preview any changes you have made on your local machine *before* you push your changes to a remote branch.
+It's always handy to be able to preview any changes you have been working on as you go - you can be confident that changes you have made are accurate and as intended.
+A nice way to do this is to use the underlying [Jupyter Book](https://jupyterbook.org/en/stable/intro.html) tool to build the book locally.
+
+This is useful because it allows you to preview any changes you have made on your local machine *before* you push your changes to a remote branch.
You can then decide if you are happy with the result and push your changes to the remote branch thus helping to keep Pull Request conversations and commit histories a bit cleaner.
## Step-by-step guide
@@ -14,27 +15,63 @@ We will be using the command line throughout this guide.
You will need to locate your "terminal" or "prompt" application on your machine.
1. Install miniconda by following the instructions for your Operating System (Windows, MacOS, Linux) at this link: https://conda.io/projects/conda/en/latest/user-guide/install/index.html#regular-installation
-2. Open your terminal app and run the `conda init` command in your terminal. You should see `(base)` in your prompt indicating that conda was successfully installed and you are now in it's base environment.
- - Note that if you are using Windows, you will need to open a program called `Anconda prompt` instead of using `cmd`.
-3. Create a new environment and install a modern version of python into it:
+
+2. Open your terminal app and run the `conda init` command in your terminal. You should see `(base)` in your prompt indicating that conda was successfully installed and you are now in its base environment.
+ - Note that if you are using Windows, you will need to open a program called `Anaconda prompt` instead of using `cmd`.
+
+3. Create a new environment and install a modern version of Python into it:
+
+ ```console
+ conda create --name the-turing-way python=3.8
```
- conda create --name the-turing-way python=3.10
+
+4. Activate the environment with:
+
+ ```console
+ conda activate the-turing-way
```
-4. Activate the environment with `conda activate the-turing-way`. Any commands we run with Python or pip from now on will use the versions of Python and pip installed into _this_ conda env, not any others
-5. Clone The Turing Way repository from GitHub to your machine using the command `git clone https://github.com/the-turing-way/the-turing-way`
-6. Navigate into the cloned repository folder using the command `cd the-turing-way`, where the `cd` command means `change directory`
-7. Then change into the sub-directory the website is built from using `cd book/website`
-8. The Turing Way Book is built using multiple python libraries. We can install these dependencies _into your conda environment_ using the following command
+
+ Any commands we run with Python or pip from now on will use the versions of Python and pip installed into _this_ conda env, not any others.
+
+5. Clone _The Turing Way_ repository from GitHub to your machine using the command:
+
+ ```console
+ git clone https://github.com/the-turing-way/the-turing-way
+ ```
+
+ ````{note}
+ To address potential barriers with slow internet connections due to the large size of this repository, you can use [partial clones](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#). Specifically, focusing on blobless clones, which are efficient for developers, involves utilizing the `--filter=blob:none` option in the git clone command.
+
+ By using `--filter=blob:none`, the initial git clone operation downloads all reachable commits and trees, while blobs (file contents) for commits are only downloaded when performing a git checkout
+
+ Here's the command to use blobless clones:
+
+ ```console
+ git clone --filter=blob:none https://github.com/the-turing-way/the-turing-way.git
```
+ ````
+
+6. Navigate into the cloned repository folder using the command `cd the-turing-way`, where the `cd` command means `change directory`.
+
+7. Then change into the sub-directory the website is built from using `cd book/website`
+
+8. The Turing Way book is built using multiple python libraries. We can install these dependencies _into your conda environment_ using the following command
+
+ ```console
pip install -r requirements.txt
```
+
where the `requirements.txt` file contains a list of python libraries
+
9. And now build the book:
- ```
+
+ ```console
jupyter-book build .
```
+
10. The output of the build process will provide output such as below that demonstrate how you can view the book locally:
- ```
+
+ ```text
===============================================================================
Finished generating HTML for book.
@@ -47,33 +84,71 @@ You will need to locate your "terminal" or "prompt" application on your machine.
===============================================================================
```
-
+
### Build the book while working on a Pull Request
+
If you would like to preview a version of the book from a certain branch (perhaps to render the book while working on a PR) then simply switch to the required branch and rebuild the book as in step 9:
- ```
+
+ ```bash
git checkout mybranch
jupyter-book build .
```
+
Follow the link as before and you will see changes specific to that branch rendered.
+### Clean up a recent build
+
+When you test your edits by building the book multiple times, it is better to clean up the last build before generating a new one.
+You can either manually delete the `book/website/_build` folder every time, or run this command:
+
+```console
+cd book/website
+jupyter-book clean .
+```
+
+More details on this process can be read in [Jupyter Book's documentation](https://jupyterbook.org/en/stable/basics/build.html?highlight=clean#clean-your-books-generated-files).
+
+
+### Check external links in the book
+
+When editing or reviewing this book locally, you can run the Sphinx link checker with Jupyter Book to check if the external links mentioned in the book are valid.
+To run the link checker, use the following command:
+
+```console
+cd book/website
+jupyter-book build . --builder linkcheck
+```
+
+The link checker checks if the each link resolves and prints the status on your terminal so that you can check and resolve any incorrect links.
+Read more about this in [Jupyter Book's documentation](https://jupyterbook.org/en/stable/advanced/html.html?highlight=check%20external#check-external-links-in-your-book).
+
## Why did we recommend using (mini)conda?
-In the step-by-step guide above, we made use of the `jupyter-book` command to build the Turing Way book. For this command to work as intended you will need a python installation on your machine.
-As with any other programming language such as R or Julia, any given python installation might look different from another due to the different packages or libraries that come with the installation.
+
+In the step-by-step guide above, we made use of the `jupyter-book` command to build the Turing Way book. For this command to work as intended you will need a Python installation on your machine.
+As with any other programming language such as R or Julia, any given Python installation might look different from another due to the different packages or libraries that come with the installation.
Over time you will likely install even more packages, or update packages to newer versions. Some packages also depend on the presence of specific versions of other packages to function, and so to ensure your local build works smoothly you will want to minimize as much mismatched dependencies as possible.
-But this can be difficult! Even with an organized, concerted effort, package management for programming languages naturally throws up dependency issues. Python packages, for reasons not discussed here, tend to suffer from dependency issues a bit more than other languages (note that all languages do!) and one guaranteed way to come across such an issue by trying to maintain all of your python projects using just one, large set of packages, each at a specific version. You simply can't cater to the needs of all package dependencies this way. https://xkcd.com/1987/
-
+But this can be difficult! Even with an organized, concerted effort, package management for programming languages naturally throws up dependency issues. Python packages, for reasons not discussed here, tend to suffer from dependency issues a bit more than other languages (note that all languages do!) and one guaranteed way to come across such an issue by trying to maintain all of your Python projects using just one, large set of packages, each at a specific version. You simply can't cater to the needs of all package dependencies this way.
+
+```{figure} https://imgs.xkcd.com/comics/python_environment.png
+---
+height: 487px
+name: python-environment
+alt: 'A humorous, black and white flowchart from XKCD depicting the complexity of managing different Python environments on a computer. It shows a tangled web of arrows and lines connecting various versions of Python installed through different methods such as Homebrew, Anaconda, and binaries from Python.org. There are also references to different tools and paths like PIP, PYTHONPATH, and system PATH, that add to the confusion. The paths weave in and out of local folders on a computer. Some of them are noted to be owned by root, making them harder to manage. The illustration is annotated with bemused and perplexed comments about the state of the Python environment, concluding with a comic punchline at the bottom that reads, "My Python environment has become so degraded that my laptop has been declared a superfund site."'
+---
+Illustration [from xkcd](https://xkcd.com/1987) describing the complexities of installing different versions of Python on your computer. Used under a [CC-BY-NC 2.5 licence](https://creativecommons.org/licenses/by-nc/2.5/deed.en).
+```
-The most relevant feature for us here is *virtual environments*.
+The most relevant feature for us here is *virtual environments*.
-conda is a package manager designed to easily create language agnostic virtual environments, where each environment contains their own separate set of packages that don't interfere with each other.
+conda is a package manager designed to easily create language agnostic virtual environments, where each environment contains their own separate set of packages that don't interfere with each other.
In fact it is best practice to create a virtual environment for each project you work on.
-We *could* just use python's built in virtualenv tool to do this, but it doesn't extend into a multi-language env like conda offers.
+We *could* just use Python's built in virtualenv tool to do this, but it doesn't extend into a multi-language env like conda offers.
-By creating a separate environment on your local machine just for The Turing Way, this is a great way to minimize those dependency issues.
+By creating a separate environment on your local machine just for _The Turing Way_, this is a great way to minimize those dependency issues.
conda also has community run channels that dedicate their time to providing you with a certain pool of packages that may be relevant to a specific project, for example the [Bioconda channel](https://github.com/bioconda/bioconda-recipes) that contains packages relevant for bioinformatics projects, and packages not necessarily found on the default channel. Other example channels are:
- r
- conda-forge
- tensorflow-macos
-These carefully curated channels also help to ensure your virtual environments contain the most appropriate packages for each of your projects.
+These carefully curated channels also help to ensure your virtual environments contain the most appropriate packages for each of your projects.
From 5a5f5d73d423338b2c8702b2345bab7b08f77993 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:41 +0000
Subject: [PATCH 067/142] Update source file newsletters-process.md
---
.../newsletters/newsletters-process.md | 54 +++++++++----------
1 file changed, 27 insertions(+), 27 deletions(-)
diff --git a/book/website/community-handbook/newsletters/newsletters-process.md b/book/website/community-handbook/newsletters/newsletters-process.md
index 4f9b1f66f2b..6983d17b8d6 100644
--- a/book/website/community-handbook/newsletters/newsletters-process.md
+++ b/book/website/community-handbook/newsletters/newsletters-process.md
@@ -1,7 +1,7 @@
# Creating a newsletter
This document provides an overview of a process we use in _The Turing Way_ for drafting, reviewing and publishing newsletters.
-Though written for _The Turing way_, these steps can be adapted for documenting newsletter for any project.
+Though written for _The Turing way_, these steps can be adapted for documenting newsletters for any project.
We only suggest using these recommendations as guides.
These should not be considered as a set of fixed rules or the "only" way one should create newsletters.
@@ -14,20 +14,20 @@ After all, these newsletters land in someone's personal mailbox and most likely
Create a new GitHub issue where throughout the month you and other community members can suggest news items as a comment.
For example, in [this issue](https://github.com/the-turing-way/the-turing-way/issues/1037), several members could suggest news items to include in the next newsletter, in this case for June 2020.
-Such GitHub issues can be published in the current newsletter inviting contributions from the readers and community members for the next month.
+Such GitHub issues can be published in the current newsletter inviting contributions from readers and community members for the next month.
### Start a draft
-There are several ways to start a draft for a Turing Way newsletter:
+There are several ways to start a draft for a _The Turing Way_ newsletter:
1. Create a new branch of _The Turing Way_ [GitHub repository](https://github.com/the-turing-way/the-turing-way/) within the appropriate directory (explained in the next subchapter on {ref}`newsletter's style guide `).
You can work on this GitHub branch locally or online through a pull request (PR).
If working online, please keep the draft mode on for your PR or add "[WIP]" (work in progress) in the title.
-2. Create the first draft on a shared HackMD when working with others to collaboratively write your draft before you transfer them on a GitHub branch.
+2. Create the first draft on a shared HackMD when working with others to collaboratively write your draft before you transfer them to a GitHub branch.
-Here is two examples of HackMDs:
+Here are two examples of HackMDs:
- Malvika's first draft: https://hackmd.io/@malvikasharan/tw-newsletter
- Anne's first draft (April 2022): https://hackmd.io/@aleesteele/ttw-newsletter-apr-22.
@@ -35,25 +35,25 @@ Here is two examples of HackMDs:
Based on what we currently publish, collect information from the listed resources for the topics described below (they can be presented in a format agreed with *The Turing Way* staff):
-* **Community meetings**: review the [community calendar](https://calendar.google.com/calendar/embed?src=theturingway%40gmail.com&ctz=Europe%2FLondon) for upcoming events such as Collaboration Café, book dash and workshops.
+* **Community meetings**: review the [community calendar](https://calendar.google.com/calendar/embed?src=theturingway%40gmail.com&ctz=Europe%2FLondon) for upcoming events such as Collaboration Cafés, book dashes and workshops.
* **News from the community**:
-- Check Twitter for updates on the [official account](https://twitter.com/turingway) and the [#TuringWay Hashtag](https://twitter.com/hashtag/TuringWay?src=hashtag_click)
-- Check Mastodon for updates on the [official account](https://fosstodon.org/@turingway) and the [#TuringWay Hashtag](https://fosstodon.org/tags/turingway)
-- See the Github repository for [issues](https://github.com/the-turing-way/the-turing-way/issues) for ongoing discussions, recently [merged PRs](https://github.com/the-turing-way/the-turing-way/pulls?q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc) and new chapters.
-- You can also ask in the [Slack channel](https://theturingway.slack.com) if someone would like to add something to the newsletter.
+ - Check X (formerly Twitter) for updates on the [official account](https://twitter.com/turingway) and the [#TuringWay Hashtag](https://twitter.com/hashtag/TuringWay?src=hashtag_click)
+ - Check Mastodon for updates on the [official account](https://fosstodon.org/@turingway) and the [#TuringWay Hashtag](https://fosstodon.org/tags/turingway)
+ - See the Github repository for [issues](https://github.com/the-turing-way/the-turing-way/issues) for ongoing discussions, recently [merged PRs](https://github.com/the-turing-way/the-turing-way/pulls?q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc) and new chapters.
+ - You can also ask in the [Slack channel](https://theturingway.slack.com) if someone would like to add something to the newsletter.
In this part, also highlight any important milestones in the project that were either established or achieved over the last month.
-* **Relevant resources and events for the community**: check Twitter, Slack and online posts for any recent publication and events from the community members, resources for training or opportunities for skill-building or any other materials like blog posts or articles published in the network that could be useful for others.
+* **Relevant resources and events for the community**: check X, Slack and online posts for any recent publication and events from community members, resources for training or opportunities for skill-building or any other materials like blog posts or articles published in the network that could be useful for others.
-* **Sections for acknowledgements and celebrations of community members**: this is the place to give shout-outs to our members who have given talks, workshops or helped *The Turing Way* in some ways, celebrate personal milestones and highlight any relevant announcements from the community members.
- * To identify talks and presentations, please scan *The Turing Way* accounts for GitHub issues, Twitter, Slack and [Zenodo Community](https://zenodo.org/communities/the-turing-way) page (for DOI).
-Since 2023, *The Turing Way* core team maintains all information about the events and activities on their [centralised event page](https://docs.google.com/spreadsheets/d/1C-VZvmFL4PnSBsv_G9ZD3dwjIYLno3NyL7oHvbplnWs/edit#gid=577525947).
+* **Sections for acknowledgements and celebrations of community members**: this is the place to give shout-outs to our members who have given talks, workshops or helped *The Turing Way* in some way, celebrate personal milestones and highlight any relevant announcements from community members.
+ * To identify talks and presentations, please scan *The Turing Way* accounts for GitHub issues, X, Slack and the [Zenodo Community](https://zenodo.org/communities/the-turing-way) page (for DOI).
+Since 2023, *The Turing Way* core team maintains all information about events and activities on their [centralised event page](https://docs.google.com/spreadsheets/d/1C-VZvmFL4PnSBsv_G9ZD3dwjIYLno3NyL7oHvbplnWs/edit#gid=577525947).
* This is also a place to share tweets from the community or mention other online interactions such as posts from recent meetings where someone talked about _The Turing Way_.
-* **In The Turing Way Orbit**: this section is the addition from 2022, which allows a dedicated section for sharing events, resources and opportunities for jobs, funding, collaboration and more from our collaborators, partners and broader research network.
+* **In The Turing Way Orbit**: this section is an addition from 2022, which allows a dedicated section for sharing events, resources and opportunities for jobs, funding, collaboration and more from our collaborators, partners and broader research network.
-The newsletter should provide relevant information about or from the contributing and new members acknowledging them openly.
+The newsletter should provide relevant information about or from contributing and new members acknowledging them openly.
There should also be opportunities for folks who have never engaged before, or may not have the capacity to actively engage but still want to stay informed.
This can include Tips & Tricks for new contributors, recent conversations in community spaces, new chapters, ideas where support is needed or resources in the project that can make new members learn ways to engage, identify paths to get started as contributors and find relatable contents like impact stories of existing members, contributor's profiles or other community-related aspects.
@@ -63,28 +63,28 @@ This can include Tips & Tricks for new contributors, recent conversations in com
Following the recommendations on {ref}`style guide for community` and {ref}`style guide for newsletters` for using images, collect a few images (maximum 2 per section).
Make sure that these images are available under a free license (like CC-BY), collected with the link of their sources, and named clearly as suggested in the style guide.
-For the twitter mentions, there is no fixed number of screenshots, but 4-6 tweets look less crowded in the newsletter.
+For X mentions, there is no fixed number of screenshots, but 4-6 tweets looks less crowded in the newsletter.
They can be edited together in one image (explained in the newsletter's style guide).
### Write about each news item
Based on the bullet points collected for each news item, create 1-2 small paragraphs using the recommendations for the language and format described in the next subchapter.
-Provide links when useful, give credits fairly to the community members who might be associated with the news item and end the paragraph with a sentence and link to more information.
+Provide links when useful, give credit fairly to the community members who might be associated with the news item and end the paragraph with a sentence and link to more information.
### Proofreading your draft
-Before sharing your draft you should do a proofread for grammar and typo.
+Before sharing your draft you should do a proofread for grammar and typos.
An online app like [Ginger Grammar Checker](https://www.gingersoftware.com/grammarcheck), [Grammarly](https://app.grammarly.com) free version, [GrammarCheck](https://www.grammarcheck.net/editor/) or [Reverso Speller](https://www.reverso.net/spell-checker/english-spelling-grammar/) can help correct any grammatical and spelling errors.
You should also double-check to make sure that the links mentioned in the draft are not broken.
-You can use online tools such as the [W3C link checker](https://validator.w3.org/checklink) or free version of [Dr. Link Check](https://www.drlinkcheck.com/).
+You can use online tools such as the [W3C link checker](https://validator.w3.org/checklink) or the free version of [Dr. Link Check](https://www.drlinkcheck.com/).
If possible, get your draft reviewed by 1-2 members.
### Updating your draft to the online repository
-If you have drafted your newsletter in a local branch, before creating a PR, please add all the images mentioned in the newsletter to the right file location: `the-turing-way/communications/newsletters/images`.
+If you have drafted your newsletter in a local branch, before creating a PR, please add all the images mentioned in the newsletter to the right location: `the-turing-way/communications/newsletters/images`.
More details about using images have been discussed in the next subchapter, {ref}`style guide`.
If you are working on a PR on GitHub, upload all the images and check if they are linked properly.
@@ -97,7 +97,7 @@ When ready, mark your PR as "Ready for Review" and tag a few contributing member
The reviewers for the newsletter can review the text for language, relevance, typos, accuracy (fact-check), appropriateness of the use of images and the overall tone.
-Reviewers can provide constructive feedback on the newsletter draft, add any missing item that they would like to highlight, suggest appropriate changes and approve the PR when ready for the draft to be published.
+Reviewers can provide constructive feedback on the newsletter draft, add any missing items that they would like to highlight, suggest appropriate changes and approve the PR when ready for the draft to be published.
After the review process, each reviewer's name can be added under the special mentions section by the author to acknowledge their work.
@@ -106,18 +106,18 @@ After the review process, each reviewer's name can be added under the special me
We are currently using [TinyLetter](https://tinyletter.com/) to publish our newsletters.
TinyLetter is a subsidiary of [MailChimp](https://mailchimp.com/), that offers a simplified interface based free service for setting up an email newsletter and sharing it with subscribers.
-Here are the steps for publishing the newsletter draft online and send by email to the subscribed members:
+Here are the steps for publishing the newsletter draft online and sending it by email to the subscribed members:
- Convert the Markdown content of the newsletter draft to HTML using [browserling.com](https://www.browserling.com/tools/markdown-to-html) by copy-pasting the Markdown content to the text box in the web application and pressing "Convert to HTML button".
- If authorised, log in to the TinyLetter account and click the “Write A Newsletter” button.
- Paste the HTML content of your draft generated by browserling.
- Make sure that the subject is written in the correct text box.
-- Click “Preview” to see how the rendered version of your message will look like.
-- Upload images separately to the Tinyletter platform (the quality of photos significantly degrades if copied automatically)
-- Adjust formatting as needed
+- Click “Preview” to see how the rendered version of your message will look.
+- Upload images separately to the TinyLetter platform (the quality of photos significantly degrades if copied automatically).
+- Adjust formatting as needed.
- Send a preview version to your email or _The Turing Way_ email (theturingway@gmail.com) to check if everything looks OK.
- Once confirmed for its format and content, the newsletter is sent to the registered members by clicking “Send to all”.
-- The [online newsletters](https://tinyletter.com/TuringWay/) are shareable by links and can be read by non-subscribed members as well.
+- The [online newsletters](https://tinyletter.com/TuringWay/) are shareable by link and can be read by non-subscribed members as well.
*(Learn to make your newsletter [here](https://www.sitepoint.com/how-start-a-newsletter-in-minutes-with-tinyletter/).)*
From 6be38ab9916d6fe0802f114205ec771674d19f28 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:42 +0000
Subject: [PATCH 068/142] Update source file newsletters-style.md
---
.../newsletters/newsletters-style.md | 32 +++++++++----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/book/website/community-handbook/newsletters/newsletters-style.md b/book/website/community-handbook/newsletters/newsletters-style.md
index 808ad5b5eb8..7e7adf7224d 100644
--- a/book/website/community-handbook/newsletters/newsletters-style.md
+++ b/book/website/community-handbook/newsletters/newsletters-style.md
@@ -6,20 +6,20 @@ In the previous subchapter, we described the process of drafting, reviewing and
In this document, we have listed some guidelines to maintain consistency across all the newsletters.
- **File format**: Draft the newsletter in [Markdown](https://en.wikipedia.org/wiki/Markdown)
-- **Filename**: Create a filename with the "newsletter_serial_MMYYYY.md " format, where "serial" should be replaced by the serial number (in numerical) of the newsletter, the month should be replaced by the short name of the month and YYYY with the year in numerical.
-- **File location on _The Turing Way_ GitHub**: The newsletters are currently stored in the path "the-turing-way/communications/newsletters/".
+- **Filename**: Create a filename with the "newsletter_serial_MMYYYY.md " format, where "serial" should be replaced by the (numerical) serial number of the newsletter, the month should be replaced by the short name of the month and YYYY with the year as a number.
+- **File location on _The Turing Way_ GitHub**: The newsletters are currently stored in the path `the-turing-way/communications/newsletters/`.
- This location also consists of a "README.md" file that has a table for all the published newsletters that are updated after each release.
- - This location has a folder called "images" that centrally holds all the images and linked to the corresponding newsletters.
-- **Dates**: "DD MM YYYY" format
+ - This location has a folder called "images" that centrally holds all the images and links to the corresponding newsletters.
+- **Dates**: "DD Month YYYY" format
- use it consistently in the entire document
- To reflect a range, use "from DD to DD Month YYYY" format.
- - Even if the sentences have reference to a day in "yesterday", "today" or "tomorrow", provide the exact date inside parenthesis so that it still makes sense if someone reads a newsletter in the future.
-- **Time**: Use time in [Greenwich Mean Time](https://greenwichmeantime.com/what-is-gmt/) (GMT) or [British Summer Time](https://greenwichmeantime.com/uk/time/british-summer-time/) (BST), followed by a link from [arewemeetingyet.com](https://arewemeetingyet.com/#form) to check the time in relative time zones
-- **Links**: Use the Markdown formatting for link like this, `[text that needs to be linked](full HTTP link)`
+ - Even if the sentences have reference to a day as in "yesterday", "today" or "tomorrow", provide the exact date inside parenthesis so that it still makes sense if someone reads a newsletter in the future.
+- **Time**: Use time in [Greenwich Mean Time](https://greenwichmeantime.com/what-is-gmt/) (GMT) or [British Summer Time](https://greenwichmeantime.com/uk/time/british-summer-time/) (BST), followed by a link from [arewemeetingyet.com](https://arewemeetingyet.com/#form) to check the time in relative time zones.
+- **Links**: Use the Markdown formatting for link like this, `[text that needs to be linked](full HTTP link)`.
- Provide links wherever useful, for example, [HackMD for Collaboration Café](https://hackmd.io/@KirstieJane/CollabCafe), [GitHub issue](https://github.com/the-turing-way/the-turing-way/issues), [registration pages](https://www.eventbrite.co.uk/) and [see details](https://github.com/the-turing-way/the-turing-way).
- - Create link for email ids using this Markdown syntax - ``[real-email-id](mailto:real-email-id)``
+ - Create links for email addresses using this Markdown syntax - ``[real-email-address](mailto:real-email-address)``.
- [Too many links](https://intelligentcontacts.com/7-tips-to-keep-your-emails-out-of-the-spam-filter/) can trigger the spam filter on a recipient's inbox. try to keep them to a mimumum if you can.
-- **Quoting others**: Use smaller than (>) symbol followed by a space before the quoted sentence. For example:
+- **Quoting others**: Use greater than (>) symbol followed by a space before the quoted sentence. For example:
`> This is my legendary quote.` will appear as:
> This is my legendary quote.
- **Header and styling**: The newsletter title is the top header.
@@ -32,20 +32,20 @@ In this document, we have listed some guidelines to maintain consistency across
- The tone should be welcoming, friendly and preferably informal.
This can be personal to the author's writing style.
- Ask more than one person to review your draft to make sure that its content is easy to understand and written clearly.
- - If using content from a language or culture different from your own, ask people with that language or culture to review your draft to make sure that contents are not misrepresented.
+ - If using content from a language or culture different from your own, ask people with that language or culture to review your draft to make sure that the content is not misrepresented.
- **Use of emojis**: It is encouraged to use emoji (*show your personality*) 😇, but keep it simple, neutral and positive.
- - Be aware that that ambiguous emojis can be misinterpreted by different readers.
+ - Be aware that ambiguous emojis can be misinterpreted by different readers.
- When in doubt, ask someone to review your draft.
- **Use of images**: Only use relevant images linked to the news item in the newsletter.
- - Make sure that the images are available under CC-BY license or approved to be reused by the owners.
+ - Make sure that the images are available under a CC-BY license or approved to be reused by the owners.
- Avoid using memes, images with political or sexual innuendo, or anything that is not directly related to the community.
- When drafting the newsletter in a HackMD, drag-n-drop an image into the editor or copy-paste an image to automatically upload the image to [Imgur](https://en.wikipedia.org/wiki/Imgur).
- - When drafting the newsletter on the GitHub, upload the images in the folder "the-turing-way/communications/newsletters/".
- - File naming convention for the images is "short-name-monthYYYY.png", where the short-name should be replaced with the identifiable short name of the image, the month should be replaced by the short name of the month and YYYY should be replaced by the year.
- - File extension can be '.jpg', '.png' or other with compatible image file type.
+ - When drafting the newsletter on GitHub, upload the images in the folder `the-turing-way/communications/newsletters/`.
+ - The file naming convention for images is `short-name-monthYYYY.png`, where the short-name should be replaced with the identifiable short name of the image, the month should be replaced by the short name of the month and YYYY should be replaced by the year.
+ - File extension can be `.jpg`, `.png` or others with compatible image file types.
- Use Markdown syntax to link the images in the newsletter: ``.
- As suggested in [_The Turing Way_ style guide](https://the-turing-way.netlify.app/community-handbook/style/style-figures.html), create an alt text for the image: ``
- Below the image, write a short descriptive title for the image followed by an empty line.
- Link title to the source such as a tweet or related event.
+ Link the title to the source such as a tweet or related event.
- When using multiple images as panels in one collective image, number each image clearly (this can be done in any photo or text editor) and provide a numbered title for each image.
See an example [here](https://github.com/the-turing-way/the-turing-way/blob/main/communications/newsletters/newsletter_14_May2020.md#tweets-from-the-community).
From 63a28b6ee97d48c4bebb55f11e55185e91a2d3c1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:42 +0000
Subject: [PATCH 069/142] Update source file newsletters-template.md
---
.../community-handbook/newsletters/newsletters-template.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/community-handbook/newsletters/newsletters-template.md b/book/website/community-handbook/newsletters/newsletters-template.md
index 03142d468a2..a9490933a9a 100644
--- a/book/website/community-handbook/newsletters/newsletters-template.md
+++ b/book/website/community-handbook/newsletters/newsletters-template.md
@@ -1,7 +1,7 @@
(ch-newsltters-template)
# Template for Drafting Newsletters
-The template outlined below is what we have been using as a guide for collecting news items for the _The Turing Way_ newsletters since September 2019.
+The template outlined below is what we have been using as a guide for collecting news items for _The Turing Way_ newsletters since September 2019.
This template has evolved over several months and in no way claims to be the 'perfect' format.
When reusing this template, you should experiment with what works for your community.
Your suggestions in the earlier subchapters are very welcome.
@@ -54,7 +54,7 @@ Find more details on these topics below 👇
- [Slack channel](https://join.slack.com/t/theturingway/shared_invite/zt-fn608gvb-h_ZSpoA29cCdUwR~TIqpBw)
- [Public Gitter channel](https://gitter.im/the-turing-way/the-turing-way)
- [YouTube Videos](https://www.youtube.com/channel/UCPDxZv5BMzAw0mPobCbMNuA)
-- [Twitter Channel](https://twitter.com/turingway)
+- [X (formerly Twitter) Channel](https://twitter.com/turingway)
You are welcome to contribute content for the next newsletter by
emailing [Malvika Sharan](mailto:msharan@turing.ac.uk).
From 91cdb57a693aa4324641099015650de8e47c330f Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:43 +0000
Subject: [PATCH 070/142] Update source file presenting.md
---
book/website/community-handbook/presenting.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/website/community-handbook/presenting.md b/book/website/community-handbook/presenting.md
index 5ca9c05d127..17b7966c211 100644
--- a/book/website/community-handbook/presenting.md
+++ b/book/website/community-handbook/presenting.md
@@ -11,16 +11,16 @@ alt: The image shows a female speaker with long dark hair standing in front of a
Giving a talk or workshop about _The Turing Way_. Illustration by Scriberia for _The Turing Way_ community, used under a CC-BY 4.0 licence. DOI: https://doi.org/10.5281/zenodo.3332807.
```
-## Planning a Talk
+## Planning a talk
Whether you are submitting an abstract to a conference or you have been invited to speak, a great thing to do is to engage _The Turing Way_ community for support and to publicize the event. Even if the talk is not open to all, you can work with other community members to refine your slides and give a practice talk. If you'd like, please post the details in Slack in the `#community` channel.
-## Preparing Slides
+## Preparing slides
Please create a GitHub issue using the ["Give a talk" issue template](https://github.com/the-turing-way/the-turing-way/issues/new?assignees=&labels=talks-and-workshops%2Cnewsletter&template=give_a_talk.yml&title=%5BTALK%5D+%3Ctitle%3E), which provides links to the resources you will need as well as a checklist for preparing your talk. You will find a range of presentation templates, as well as past presentations, in the [Promotion Pack](https://drive.google.com/drive/folders/1mzGmbJkPnP5q1goQesxDc_E5zAPL0eTF?usp=sharing) folder on Google Drive. Feel free to download the templates and use the slides as a guide for style and content. You can also see past talks on _The Turing Way's_ [community page on Zenodo](https://zenodo.org/communities/the-turing-way/?page=1&size=20).
-## Giving a Talk
+## Giving a talk
We ask that you include certain acknowledgments in your talk to make sure contributors are credited. You'll find all the info you need in the presentation templates as well as the GitHub issue checklist.
-## After Your Talk
+## After your talk
Keep spreading the word! Please archive your slides in two formats: their original (editable) format and as a PDF. If you don't know how to convert PowerPoint or Google slides to PDF, see these [instructions](https://www.wikihow.com/Convert-Powerpoint-to-PDF); following these instructions helps preserve accessibility features for people using screen readers. You can archive your slides on [Zenodo](https://zenodo.org/communities/the-turing-way/), and don't forget to tag "the-turing-way" under Communities.
Please make sure that you credit all of the contributors and presenters of your presentation as authors in the Zenodo upload form. If possible, link to any previous talks where you have used additional slides outside of the provided _The Turing Way_ presentation templates - this can be done in the description part of the upload form.
From 4a517dc1a7e5c4843ca0c33334b6b7f7c7d4ba86 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:43 +0000
Subject: [PATCH 071/142] Update source file style.md
---
book/website/community-handbook/style.md | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)
diff --git a/book/website/community-handbook/style.md b/book/website/community-handbook/style.md
index cf1a1e5e748..4cb3026b949 100644
--- a/book/website/community-handbook/style.md
+++ b/book/website/community-handbook/style.md
@@ -24,6 +24,30 @@ There is no one alive who is youer than you.
- Dr Seuss
```
+### A note on bullet points
+
+If you want to add multiple sentences inside a bullet point, we recommend indenting the sentences following the initial sentence with two spaces.
+Consider the example below.
+
+```markdown
+Dr Seuss said:
+- Today was good. Today was fun. Tomorrow is another one.
+- The more that you read, the more things you will know. The more that you learn, the more places you'll go.
+```
+
+Similarly to the example in the section above, we should change this to have the sentences on separate lines:
+
+```markdown
+Dr Seuss said:
+- Today was good.
+ Today was fun.
+ Tomorrow is another one.
+- The more that you read, the more things you will know.
+ The more that you learn, the more places you'll go.
+```
+
+This will render the same as the example with all sentences in one bullet point line, but will make it easier to see changes in pull requests.
+
## Opinions are welcome, but ...
_The Turing Way_ book is intended to be only *lightly* opinionated.
From 6c5296303cfd4fbd1b304c7592d919bd9eee5fc0 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:43 +0000
Subject: [PATCH 072/142] Update source file style-citing.md
---
book/website/community-handbook/style/style-citing.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/style/style-citing.md b/book/website/community-handbook/style/style-citing.md
index 4ec14bc8233..f2c232e95af 100644
--- a/book/website/community-handbook/style/style-citing.md
+++ b/book/website/community-handbook/style/style-citing.md
@@ -25,7 +25,7 @@ You can edit reference file locally using a method from the following:
- Edit [`references.bib`][turingbib] directly using a text editor
- Edit [`references.bib`][turingbib] directly using a managing program such as [JabRef](http://www.jabref.org/) (Linux, Windows, macOS) or [BibDesk](https://bibdesk.sourceforge.io/) (macOS)
-We use a standard bibtex format to add a new entry.
+We use a standard BibTeX format to add a new entry.
For example, there is an entry in the [`references.bib`][turingbib] file as:
```
From 635546708e88d0aadaf2c03717ab78a6f818a40d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:44 +0000
Subject: [PATCH 073/142] Update source file style-crossref.md
---
.../style/style-crossref.md | 60 ++++++-------------
1 file changed, 17 insertions(+), 43 deletions(-)
diff --git a/book/website/community-handbook/style/style-crossref.md b/book/website/community-handbook/style/style-crossref.md
index 274f324a59f..9b0e7ae5030 100644
--- a/book/website/community-handbook/style/style-crossref.md
+++ b/book/website/community-handbook/style/style-crossref.md
@@ -59,60 +59,49 @@ We have created a label for that chapter called `rr-overview` by adding the labe
# Overview
```
-Similarly, for different subchapters we recommend extending the label name with another placeholder for subchapter's name.
+Similarly, for different subchapters we recommend extending the label name with another placeholder for the subchapter's name.
For example, `rr-overview-resources` is a label in the guide "Reproducible Research" (rr) for the subchapter "Resources" for the "Overview" chapter (overview-resources).
This label can be created by using the following directive in the corresponding file:
```
-(sectioninitials-filename)=
+(rr-overview-resources)=
# Resources
```
-In the same manner, for different sections in a subchapters we recommend extending the label name with another placeholder.
+In the same manner, for different sections in a subchapter we recommend extending the label name with another placeholder.
This can be chosen by the authors, which should be a short yet sensible name for the section where the label is being created.
-For example, `rr-overview-resources-addmaterial` is a label in the guide "Reproducible Research" (rr) for the subchapter "Resources" for the "Overview" chapter (overview-resources) for the section for "Additional Materials" (addmaterails).
+For example, `rr-overview-resources-addmaterial` is a label in the guide "Reproducible Research" (rr) for the subchapter "Resources" for the "Overview" chapter (overview-resources) for the section for "Additional Materials" (addmaterial).
This label can be created in the corresponding file for the suggested section name using the following directive:
```
-(sectioninitials-filename-section)=
+(rr-overview-resources-addmaterial)=
## Additional Material
```
### Examples of cross-referencing
-**Examples for cross-referencing sections of chapters and subchapters**
-
-We will use examples for the chapters in "Reproducible Research" guide located in the `book/website` directory.
+Here we provide examples of how to cross-reference chapters, sections of chapters and subchapters.
+We will use examples for the chapters in the "Reproducible Research" guide located in the `book/website` directory.
-**_Case 1_**: When you cross-reference a section of the chapter within the same file _before_ a label has been created.
+**_Example 1_**: Cross-referencing a chapter or subchapter (chapter/subchapter).
-Taking the previous example of `rr-overview-resources-addmaterial`, we can use this label to cross-reference
-it in an earlier section within the same file using the following:
+On the landing page of the chapter "Open Research", we have created a label `rr-open`.
+We can cross-reference it at any other point in the book by using the following:
```
-{ref}`rr-overview-resources-addmaterial`
+{ref}`rr-open`
```
-This will appear in the online book like so: {ref}`rr-overview-resources-addmaterial`.
-
-**_Case 2_**: When you cross-reference a section of the chapter within the same file _after_ a label has been created.
-
-In the same subchapter "Resources", we have created a label `rr-overview-resources-reading` for the section "Further Reading".
-We can cross-reference it in a later section within the same file using the following:
-
-```
-{ref}`rr-overview-resources-reading`
-```
+It will appear in your chapter like this: {ref}`rr-open`.
-It will appear in your chapter like this: {ref}`rr-overview-resources-reading`.
+It doesn't matter whether the label appears before or after the reference, or even on a completely different page.
+The same syntax can be used whether you are cross-referencing chapters and subchapters within the same chapter, or in other chapters across the book.
-**_Case 3_**: When you cross-reference a section of a chapter in a different file (chapter) before or after a label has been created.
+**_Example 2_**: Cross-referencing a section of a chapter.
In the subchapter "Definitions" of the "Overview" chapter, we have created a label
`rr-overview-definitions` for the section "Table of definitions for reproducibility".
-
-We can cross-reference it in a different subchapter or chapter.
-In this case, let's cross-reference it in the landing (main) page of the "Overview" chapter by using the following:
+We can cross-reference it elsewhere in the book by using the following:
```
{ref}`rr-overview-definitions`
@@ -120,22 +109,7 @@ In this case, let's cross-reference it in the landing (main) page of the "Overvi
It will appear in your chapter like this: {ref}`rr-overview-definitions`.
-Though we are demonstrating this example for subchapters within the same chapter ("Overview"), the similar syntaxes can be used for cross-referencing in other chapters within the book.
-
-**Examples for Cross referencing chapters and subchapters**
-
-**_Case 4_**: Cross-referencing a chapter or subchapter in a different file (chapter/subchapter) before or after a label has been created.
-
-For example, in the landing page of the chapter "Open Research", we have created a label `rr-open`.
-We can cross-reference it in the section "What to learn next?" in a different subchapter "Resources" of the "Overview" chapter by using the following:
-
-```
-{ref}`rr-open`
-```
-
-It will appear in your chapter like this: {ref}`rr-open`.
-
-Though we are demonstrating this example for cross-referencing chapters and subchapters across the book, the same syntax can be used for cross-referencing subchapters within the same chapter.
+As before it doesn't matter where the label appears relative to the reference, this same syntax can be used whether you are cross-referencing sections within the same chapter, or in other chapters across the book.
### Providing an alternative title for the references
From 8c335d63ddf6ee7a8be602ba5993bda924de2bd6 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:45 +0000
Subject: [PATCH 074/142] Update source file style-custom-styling.md
---
book/website/community-handbook/style/style-custom-styling.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/style/style-custom-styling.md b/book/website/community-handbook/style/style-custom-styling.md
index 39b86ee45d0..17e89130849 100644
--- a/book/website/community-handbook/style/style-custom-styling.md
+++ b/book/website/community-handbook/style/style-custom-styling.md
@@ -60,7 +60,7 @@ Before writing any CSS, inspect the book's HTML source code first.
This gives you an idea of what elements to target, and may help you figure out how to structure your CSS rules.
All web browsers allow you to view the source code of websites easily.
-On computers running the Windows OS, this is done using `CTRL + U`.
+On computers running the Windows OS or Linux, this is done using `CTRL + U`.
For computers running Mac OS, this is done using `Option + Command + U`.
Once you have determined the element(s) you want to modify, write your CSS in _The Turing Way's_ [stylesheet file](https://github.com/the-turing-way/the-turing-way/blob/main/book/website/_static/book-stylesheet.css).
From 10c4b8937454844981506e1c576c4524ec494c3a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:45 +0000
Subject: [PATCH 075/142] Update source file style-figures.md
---
.../community-handbook/style/style-figures.md | 32 +++++++++----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/book/website/community-handbook/style/style-figures.md b/book/website/community-handbook/style/style-figures.md
index 2c332c14c9f..667cd95b462 100644
--- a/book/website/community-handbook/style/style-figures.md
+++ b/book/website/community-handbook/style/style-figures.md
@@ -1,7 +1,7 @@
(ch-style-figures)=
# Using figures in _The Turing Way_
-We encourage you to use images in _The Turing Way_ book chapters to help readers understand the concpets discussed in the chapter better.
+We encourage you to use images in _The Turing Way_ book chapters to help readers understand the concepts discussed in the chapter better.
This section of the style guide will explain how to use [Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/) (MyST) format to add them to the book with appropriate {ref}`alt text` and {ref}`captions`.
This is sometimes tricky, refer to the {ref}`ch-style-figures-advanced` section for troubleshooting.
@@ -20,9 +20,9 @@ Please ensure that you attribute the image files fairly and avoid files that are
The following recommendations will help you to check that you're using the images according to their licence permissions:
* You can source images in the public domain ([CC0 licence](https://creativecommons.org/share-your-work/public-domain/cc0)) or images shared under an appropriate permissive license.
- Images that are available under CC-BY 4.0 permissions are very easily interoperable with the _The Turing Way_ as this is the same licence as the rest of the content for the book.
+ Images that are available under CC-BY 4.0 permissions are very easily interoperable with _The Turing Way_ as this is the same licence as the rest of the content for the book.
* If you are using your own images, they will be made available under a [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.ast) licence as with the rest of the book.
-* If an image (for example that you have found on the internet), is not available under an open licence please contact the original author of the image and seek permission to reproduce their image.
+* If an image (for example that you have found on the internet) is not available under an open licence please contact the original author of the image and seek permission to reproduce their image.
Make sure to ask them **how they would like to be credited** in the caption for the figure.
In general, make sure to always cite the image properly as directed by the image owners.
@@ -35,7 +35,7 @@ Every image file used in this book should be located in the directory `book/webs
If you use a new image file, please add the file in the `figures` directory by either uploading via GitHub, or adding locally and pushing the change online when using git.
Please upload `.jpg`, `.png`, or `.svg` files that are under 1MB to allow them to load faster in the online book.
-If your file is larger than 1MB, please use a local image editing tools, or online tool like [IMG2GO](https://www.img2go.com/compress-image) to compress your file.
+If your file is larger than 1MB, please use a local image editing tool, or online tool like [IMG2GO](https://www.img2go.com/compress-image) to compress your file.
To name your image file, please use all-lowercase and separate words with hyphens (-).
@@ -43,10 +43,10 @@ To name your image file, please use all-lowercase and separate words with hyphen
## Alternative text
Alternative text or alt text are used for describing the appearance and function of an image on an HTML page for users who cannot see it.
-Alt text is often used by visually impaired people who use assistive technology such as the screen readers.
+Alt text is often used by visually impaired people who use assistive technology such as screen readers.
Adding alt texts to figures is one of the first principles of web accessibility as it enables the screen reader software to read an alt text to its users helping them understand/explain the content.
-If an image link break, alt texts are still functional and read as intended by the assistive technology.
+If an image link breaks, alt texts are still functional and read as intended by the assistive technology.
:::{tip}
**Apply best practices for describing an image in an alt text.**
@@ -55,7 +55,7 @@ Writing alt text is all about context.
Being aware of how the image is presented and the context in which it sits will give any assistive technology user a better experience.
If you’re writing about an image of a painting, you might want to consider if the style of painting is important, does knowing the painter’s name add value? It’s up to you to decide what information is essential.
-Here are a few of things to keep in mind when writing alt text:
+Here are a few things to keep in mind when writing alt text:
* Alt text should be specific and not overly descriptive.
* Good descriptions are concise, but describe what’s in your images accurately enough to understand their context – imagine you are describing a picture in a just 280 characters.
* Stay clear of repetition.
@@ -86,16 +86,16 @@ You can resize figures to adjust how they appear in our chapters using the param
Using the parameter: `name`, you can reference figures in other chapters in a similar manner as defined in {ref}`ch-style-crossref`.
**The example figure we have use here can be explained with this alt text:**
-*Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.*
+*Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seems to be checking if everything is ok - gesturing a thumbs-up.*
-All the components of your figure (image file location, size, name, alt text and title) can be encapsulated in section within a markdown file using the following directive:
+All the components of your figure (image file location, size, name, alt text and title) can be encapsulated in a section within a markdown file using the following directive:
````
```{figure} ../../figures/file-collection.*
---
height: 500px
name: file-collection
-alt: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.
+alt: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seems to be checking if everything is ok - gesturing a thumbs-up.
---
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
@@ -107,7 +107,7 @@ When all these components are used correctly, a figure included in a file will b
---
height: 500px
name: file-collection
-alt: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seem to be checking if everything is ok - gesturing a thumbs-up.
+alt: Cartoon-like sketch of a woman looking through a big file drawer, where documents are arranged systematically indicated by versions. She is smiling and waving at her colleague who is standing next to the file drawer and seems to be checking if everything is ok - gesturing a thumbs-up.
---
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
@@ -179,12 +179,12 @@ After a figure is added in a chapter, it can be referred in other files using th
For more advanced parameters, please visit the [Jupyter Book Documentation](https://jupyterbook.org/content/figures.html).
That page includes information on how to [scale and align](https://jupyterbook.org/content/figures.html#figure-scaling-and-aligning) the figures, and how to add the figures or their captions to the [margins](https://jupyterbook.org/content/figures.html#margin-captions-and-figures) of the book.
-We've noticed a couple of "gotchas" from contributors to _The Turing Way_ and we'll try to keep this section of the guide up to date for anyone else learning the MyST syntax for figures
+We've noticed a couple of "gotchas" from contributors to _The Turing Way_ and we'll try to keep this section of the guide up to date for anyone else learning the MyST syntax for figures.
-* If things do not work, looking at the **deploy log** (visible at the beginning of your PR) might well give you hints about the issues are.
-* Figure path are case-sensitive, make sure the name of the file is all lowercase
-* `name:` is for including in reference links, it cannot have spaces
-* The path to the figure will depend on the position of the .md file in the repo (one or two folders away from `website` will give `../` or `../../` respectively.
+* If things do not work, looking at the **deploy log** (visible at the beginning of your PR) might well give you hints about what the issues are.
+* Figure paths are case-sensitive, make sure the name of the file is all lowercase.
+* `name:` is for including in reference links, it cannot have spaces.
+* The path to the figure will depend on the position of the .md file in the repo (one or two folders away from `website` will give `../` or `../../` respectively).
* You can choose to include the file extension with your path, or you can use the format `path/filename.*` to allow Jupyter Book to decide which file to use in the case that multiple filetypes with the same name exist. Jupyter Book will [choose the one most appropriate to the intended output](https://jupyterbook.org/en/stable/content/figures.html#supported-image-formats). This is useful as it means that filetypes can be changed without breaking the pages that use those files.
* You cannot have line breaks in the alt text, but you can have it in the caption.
* Both `:` and `"` have syntactic meaning for Sphinx.
From 01694951be26d5daf2e08cd3fd851d804b36558f Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:46 +0000
Subject: [PATCH 076/142] Update source file style-more-styling.md
---
book/website/community-handbook/style/style-more-styling.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/style/style-more-styling.md b/book/website/community-handbook/style/style-more-styling.md
index 7b0893e4fbe..0c60a962f60 100644
--- a/book/website/community-handbook/style/style-more-styling.md
+++ b/book/website/community-handbook/style/style-more-styling.md
@@ -77,4 +77,4 @@ This is a stern warning!
```
There are many more ways to customise content blocks to suit your writing needs.
-Refer to the [Jupyter Book documentation](https://jupyterbook.org/content/content-blocks.html#notes-warnings-and-other-admonitions) and the [Admonition Demo page](https://sphinx-book-theme.readthedocs.io/en/latest/reference/demo.html#admonitions) for more recommendations.
+Refer to the [Jupyter Book documentation](https://jupyterbook.org/content/content-blocks.html#notes-warnings-and-other-admonitions) and the [Admonition Demo page](https://sphinx-book-theme.readthedocs.io/en/latest/reference/kitchen-sink/admonitions.html) for more recommendations.
From 230e0f417d28facae0022c33bc706e82d6f39837 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:46 +0000
Subject: [PATCH 077/142] Update source file templates.md
---
book/website/community-handbook/templates.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/templates.md b/book/website/community-handbook/templates.md
index fd00b6206ec..f651ac93518 100644
--- a/book/website/community-handbook/templates.md
+++ b/book/website/community-handbook/templates.md
@@ -15,7 +15,7 @@ Illustration of a process of sketching. [Royalty free image from Many Pixels](ht
(ch-template-bookdash)=
## Book Dash Events
-There are four MarkDown templates for the shared notes (HackMD), feedback and GitHub issue for organising and running _The Turing Way_ book dash events.
+There are four MarkDown templates for the shared notes (HackMD), feedback and GitHub issue for organising and running _The Turing Way_ Book Dash events.
These templates can be reused and adapted for different events within and outside _The Turing Way_ community.
- {ref}`HackMD Template for the Index Page`
From 87583c399b4beef013d7a4e5f2632b27460b0628 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:47 +0000
Subject: [PATCH 078/142] Update source file template-bookdash-index.md
---
.../community-handbook/templates/template-bookdash-index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/templates/template-bookdash-index.md b/book/website/community-handbook/templates/template-bookdash-index.md
index f07151558d9..0dd6fe8990e 100644
--- a/book/website/community-handbook/templates/template-bookdash-index.md
+++ b/book/website/community-handbook/templates/template-bookdash-index.md
@@ -188,7 +188,7 @@ Any day-to-day feedback during the event can be directly shared in the main even
- Slack Channel: [Invitation link](https://join.slack.com/t/theturingway/shared_invite/zt-fn608gvb-h_ZSpoA29cCdUwR~TIqpBw)
- New to Slack? [See this quick start guide](https://hackmd.io/@turingway/slack-guide)
- Mailing list: https://tinyletter.com/TuringWay/
-- Twitter account: https://twitter.com/turingway
+- X (formerly Twitter) account: https://twitter.com/turingway
### Acknowledging your contributions to _The Turing Way_
From b796be0369a4a62cf262081e884d6b5316a3bf3a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:48 +0000
Subject: [PATCH 079/142] Update source file template-bookdash-notes.md
---
.../community-handbook/templates/template-bookdash-notes.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/community-handbook/templates/template-bookdash-notes.md b/book/website/community-handbook/templates/template-bookdash-notes.md
index b2f10bb261c..cf0cbd533f5 100644
--- a/book/website/community-handbook/templates/template-bookdash-notes.md
+++ b/book/website/community-handbook/templates/template-bookdash-notes.md
@@ -57,7 +57,7 @@ All time provided in London Time (UTC+1). Please use this link to convert in you
*Please add your name to this list, but remember that this is a public document, so use a pseudonym if you'd prefer, or just feel free to leave your name off.*
-*Name (pronouns - optional) / Institute / Twitter, GitHub / icebreaker: What song/music/artist/album puts you in a good mood!* :musical_score:
+*Name (pronouns - optional) / Institute / X, GitHub / icebreaker: What song/music/artist/album puts you in a good mood!* :musical_score:
*
*
@@ -72,7 +72,7 @@ All time provided in London Time (UTC+1). Please use this link to convert in you
* Book is hosted online at: https://the-turing-way.netlify.com
* Join Slack channel: An email will be sent to you
* Join the [mailing list to receive newsletter](https://tinyletter.com/TuringWay)
-* Follow on Twitter: [@turingway](https://twitter.com/turingway)
+* Follow on X: [@turingway](https://twitter.com/turingway)
### :busts_in_silhouette::speech_balloon: Planning your contributions: breakout (10 minutes)
From 1978a4684d33721d19f07473ee2a145c773f61e8 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:48 +0000
Subject: [PATCH 080/142] Update source file template-coworking-collabcafe.md
---
.../templates/template-coworking-collabcafe.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/templates/template-coworking-collabcafe.md b/book/website/community-handbook/templates/template-coworking-collabcafe.md
index acc3aab636e..60b67437249 100644
--- a/book/website/community-handbook/templates/template-coworking-collabcafe.md
+++ b/book/website/community-handbook/templates/template-coworking-collabcafe.md
@@ -1,7 +1,7 @@
(ch-template-coworking-collabcafe)=
# Collaboration Cafe Call Template
-*A permanent document exists in the HackMD: [https://hackmd.io/@KirstieJane/CollabCafe](https://hackmd.io/@KirstieJane/CollabCafe) that is regularly updated with the empty template for next event.*
+*A permanent document exists in the HackMD: [https://hackmd.io/@KirstieJane/CollabCafe](https://hackmd.io/@KirstieJane/CollabCafe) that is regularly updated with the empty template for the next event.*
## _The Turing Way_ online Collaboration Cafe | DATE MONTH YEAR
From f1a581419a367169c3ff14bd29b1d436f010ee75 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:49 +0000
Subject: [PATCH 081/142] Update source file template-newsletter-draft.md
---
.../community-handbook/templates/template-newsletter-draft.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/community-handbook/templates/template-newsletter-draft.md b/book/website/community-handbook/templates/template-newsletter-draft.md
index b5837efd8f2..8abaa1cbe6d 100644
--- a/book/website/community-handbook/templates/template-newsletter-draft.md
+++ b/book/website/community-handbook/templates/template-newsletter-draft.md
@@ -49,7 +49,7 @@ Find more details on these topics below 👇
- [Slack channel](https://join.slack.com/t/theturingway/shared_invite/zt-fn608gvb-h_ZSpoA29cCdUwR~TIqpBw)
- [Public Gitter channel](https://gitter.im/the-turing-way/the-turing-way)
- [YouTube Videos](https://www.youtube.com/channel/UCPDxZv5BMzAw0mPobCbMNuA)
-- [Twitter Channel](https://twitter.com/turingway)
+- [X (formerly Twitter) Channel](https://twitter.com/turingway)
You are welcome to contribute content for the next newsletter by
emailing [Malvika Sharan](mailto:msharan@turing.ac.uk).
From 4ca60ccd487e16a3e3b419c0e37259cd0a9ad60e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:50 +0000
Subject: [PATCH 082/142] Update source file translation-getting-started.md
---
.../translation/translation-getting-started.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/book/website/community-handbook/translation/translation-getting-started.md b/book/website/community-handbook/translation/translation-getting-started.md
index 42eae953285..0f640cc8cd2 100644
--- a/book/website/community-handbook/translation/translation-getting-started.md
+++ b/book/website/community-handbook/translation/translation-getting-started.md
@@ -40,7 +40,7 @@ alt: Sign up in Crowdin or log in before you start the translation. You can also
---
```
-You can either create an account in Crowdin by filling the requested details or through sign up using your GitHub, Facebook, Twitter, GitLab or Google account.
+You can either create an account in Crowdin by filling the requested details or through sign up using your GitHub, Facebook, X (formerly Twitter), GitLab or Google account.
```{warning}
_The Turing Way_ is using [Crowdin Enterprise](https://crowdin.com/enterprise), which is not connected to [crowdin.com](https://crowdin.com/) and needs a separate account.
@@ -63,8 +63,7 @@ alt: Crowdsourcing page in Crowdin which has three tabs, one showing the languag
- They are essential to harmonise and standardise translations.
Make sure you read them before you start translating for the first time.
If you are starting a new language, please make sure you create a repository in the GitHub organisation with your language guidelines.
- Feel free to comment these guidelines and suggest new terms anytime. This can be done in the corresponding repositories or in _The Turing Way_ issues
-
+ Feel free to comment on these guidelines and suggest new terms anytime. This can be done in the corresponding repositories or in _The Turing Way_ issues.
- **Choose the language you want to contribute to.** We have currently 4 languages with active contributors, which are Spanish, Arabic, Portuguese and Chinese.
```{admonition} Add New Language
@@ -81,7 +80,7 @@ alt: You can add a new language by contacting one of the managers.
```
- **Start Translating chapters from the translation priorities list.**
- - Each language has the Translation Priorities list, which you can find in the README file.
+ - Each language has a Translation Priorities list, which you can find in the README file.
Choose one of the high priority files.
- You can view the translation priorities list in the task tab in Crowdin, they are also marked with a red arrow. The same list is copied below:
- **Urgent** (Welcome, afterword)
@@ -90,7 +89,8 @@ alt: You can add a new language by contacting one of the managers.
- **Priority +** (Version Control, Overview of Project Design, Creating Project Repositories)
- **Intermediate** (Overview of the Guide for Communication, Making Research Objects Citable, Communications in Open Source Projects, Getting Started With GitHub, Research Infrastructure Roles, Introduction to Research Ethics)
- - In order to navigate to the tasks tab inside Crowdin, you need to click in "Go to the Console" at the top right and navigate back to _The Turing Way_ project which will direct you to a similar interface but with additional tabs on the left, one of the these is the task tab.
+ - In order to navigate to the tasks tab inside Crowdin, you need to click in "Go to the Console" at the top right and navigate back to _The Turing Way_ project which will direct you to a similar interface but with additional tabs on the left.
+ One of these is the task tab.
In the Tasks, we assign tasks to get files translated or proofread by the community or set the due dates and receive notifications about the changes and updates in tasks.
```{figure} ../../figures/tasks-crowdin.gif
@@ -106,7 +106,7 @@ alt: You can add a new task to Crowdin by clicking on the console at the top and
```{admonition} Top Tip
:class: tip
-The arrow icon next to the high priority files are always pointing up and coloured red!
+The arrow icons next to the high priority files are always pointing up and coloured red!
```
```{figure} ../../figures/choose-file-crowdin.gif
From df965bccd66b5dd14eec57150d828e3e449e3da5 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:51 +0000
Subject: [PATCH 083/142] Update source file translation-hello-crowdin.md
---
.../translation/translation-hello-crowdin.md | 62 ++++++++++++-------
1 file changed, 41 insertions(+), 21 deletions(-)
diff --git a/book/website/community-handbook/translation/translation-hello-crowdin.md b/book/website/community-handbook/translation/translation-hello-crowdin.md
index ccda876be67..881e8a8366c 100644
--- a/book/website/community-handbook/translation/translation-hello-crowdin.md
+++ b/book/website/community-handbook/translation/translation-hello-crowdin.md
@@ -2,12 +2,12 @@
# Your Gateway to Crowdsourced Localisation
-[Crowdin](https://crowdin.com/) editor is your friend.
-You can use it to change translation language, proofread, add comments for contributors, contact the managers, vote translations, view suggestions for translation from translation memory or find Machine Translation from Google, Crowdin, DeepL, and others.
+The [Crowdin](https://crowdin.com/) editor is your friend.
+You can use it to change translation language, proofread, add comments for contributors, contact the managers, vote on translations, view suggestions for translation from Translation Memory or find Machine Translation from Google, Crowdin, DeepL, and others.
-Once you click on any file, you will be directed to the comfortable mode in Crowdin crowdsourcing editor.
-There are different modes and editors inside Crowdin but we will only go through comfortable mode and proofreader mode in Crowdin crowdsourcing editor.
-You can find more information about Crowdin Editor from the [documentation here](https://support.crowdin.com/enterprise/getting-started-for-translators/).
+Once you click on any file, you will be directed to the comfortable mode in the Crowdin crowdsourcing editor.
+There are different modes and editors inside Crowdin but we will only go through comfortable mode and proofreader mode in the Crowdin crowdsourcing editor.
+You can find more information about the Crowdin Editor from the [documentation here](https://support.crowdin.com/enterprise/getting-started-for-translators/).
The comfortable mode is divided into four sections:
1. **Left Sidebar:** It contains all strings in the file that you will translate.
@@ -24,7 +24,7 @@ alt: The crowdin editor with four sections labelled from number 1-4.
---
```
-As shown in the image below, the Middle-top area (3) is the main working area with the source string on the top, and the section where you can type in translations below.
+As shown in the image above, the Middle-top area (3) is the main working area with the source string on the top, and the section where you can type in translations below.
Crowdin will show you suggestions for translation carried out using three different engines (Google Translate, Crowdin Translate, DeepL), which will show you several possible translations that you can further edit.
```{admonition} Add Translation Engine
@@ -40,11 +40,11 @@ Strings may have the following statuses:
-  - Approved
-  - Hidden (visible only for project managers and proofreaders)
-An active string is highlighted with the yellow color but you can turn on/off color highlight of strings by clicking on  and - show translation preview using .
+An active string is highlighted with the yellow color but you can turn on/off color highlight of strings by clicking on  and show translation preview using .
-Crowdin editor won't only show you suggestions of a translation made by the translation engine but also suggestions from translation in different projects that shared their translation memory (TM) with _The Turing Way_ and will be detected if the string is similar by 70%.
+Crowdin editor won't only show you suggestions of a translation made by the translation engine but also suggestions from translation in different projects that shared their Translation Memory (TM) with _The Turing Way_ and will be detected if the string is has a similarity above 70%.
This avoids duplication of effort.
-If you would like to re-use our translation memory (TM) in your own open-source projects, feel free to contact our Translation and Localisation leads.
+If you would like to re-use our Translation Memory (TM) in your own open-source projects, feel free to contact our Translation and Localisation leads.
```{figure} ../../figures/translation-memory.*
---
@@ -55,15 +55,16 @@ alt: Translation_Memory suggesting a translation for a project which was carried
```
```{important}
-We can re-use translation memory (TM) from projects translated inside and outside Crowdin (for example, TransLocalize, Crowdin, Transifex) or even that were translated manually from Google docs.
+We can re-use Translation Memory (TM) from projects translated inside and outside Crowdin (for example, TransLocalize, Crowdin, Transifex) or even that were translated manually from Google docs.
-Get in touch if you want to share the translation memory (TM) of a previously translated project.
+Get in touch if you want to share the Translation Memory (TM) of a previously translated project.
```
## Adding terms to the glossary
In order to translate the project's terminology properly and consistently, we keep them in a Glossary.
-In the Glossary, you can create, store, and manage all the project terminology in one place.
+In the Glossary, you can create, store, and manage all the project terminology in one place.
+The use of glossaries in each language team is optional, but heavily recommended. Each project automatically generates its own Glossary when it's created, and it can be filled with content by each project team.
```{figure} ../../figures/Glossary.*
---
@@ -71,12 +72,14 @@ name: Glossary_
width: 90%
alt: Glossary in Crowdin which is table showing the terms in multiple languages.
---
+View of the full Glossary of the different languages.
+Only Crowdin contributors with manager role can access this view.
```
-```{admonition} Tip
-:class: tip
-You can upload a glossary or share glossaries across different projects.
-```
+
+To add terms to the Glossary you need to double-select a term, and then select the option "create term".
+A new window will appear showing both the English and [language] explanations for that term.
+If the term is new in that language, you'll need to specify the equivalent word in your language for that English term.
```{figure} ../../figures/adding-glossary.*
---
@@ -84,12 +87,20 @@ name: Adding-glossary
width: 90%
alt: The Crowdin editor shows the glossary term underlined and you can also add new one by highlighting the term and clicking on add term. A new window will be prompt where you can fill its details.
---
+Workflow for adding new terms while translating.
```
-The terms that were added to the project glossary will be underlined in the source string.
+For a file that needs to be translated, you can search which words from it are present in the Glossary by selecting the "Terms" icon on the Crowdin editor.
+
+The terms that were added to the project Glossary will be underlined in the source string.
You can check additional explanations added to the term for an accurate translation.
+```{admonition} Tip
+:class: tip
+You can upload a glossary or share glossaries across different projects. To do so, contact a contributor with Crowdin manager role.
+```
+
## Proofreading
Proofreading mode will show you the original string, the current translation and some options proposed by Crowdin.
@@ -118,18 +129,18 @@ alt: The proofreading mode in Crowdin editor where you can click in the tick to
When you are proofreading, pay extra attention to punctuation.
You can either choose one of these or edit directly in each string's field.
-When you reach a satisfactory translation, click on Save.
+When you reach a satisfactory translation, select Save.
## Adding Comments
-You can discuss the meaning of the source string or report the issues regarding the source strings in the comment tab (**Right sidebar**).
+You can discuss the meaning of the source string or report issues regarding the source strings in the comment tab (**Right sidebar**).
You can also use `@` and the username to direct your message to a specific person.
You can point out if the current translation is wrong or if the translation lacks contextual information.
The issues are reported to the project managers to correct mistakes or add context and resolve the issues.
The terms that were added to the project glossary will be underlined in the source string.
-You can check additional explanation added to the term for the accurate translation.
+You can check additional explanations added to the term to help with accurate translation.
A project manager can also give you permission to add terms to the project glossary.
# Embracing Global Accessibility through Localisation and Crowdsourcing
@@ -137,6 +148,15 @@ A project manager can also give you permission to add terms to the project gloss
The process of translating _The Turing Way_ into multiple languages through crowdsourcing has been a remarkable endeavor, showcasing the power of collaboration and inclusivity within the open-source community.
Through the collective efforts of volunteers and contributors worldwide, the project has successfully bridged language barriers and expanded its reach to diverse communities.
+```{important}
+The translation process is an excellent opportunity not only to bring _The Turing Way_ to your language, but also to review and improve its content and make it more accessible and localisable for everyone.
+- If you run into alt text (which should be translated) that is incomplete, too short, or doesn't correspond to the content it's referring to, please create an Issue so we can address it.
+- Some sections of the _The Turing Way_ may be written in a way that makes it difficult for language teams to translate them.
+For example, translation teams working with languages with gender marks may find it challenging to translate particular contents in a inclusive manner.
+There can also be references to very specific contexts in some countries, or certain "internal jokes" that get (literally) lost in translation.
+You can help make the handbook more localisable by submitting an Issue that describes the problem, or even better, a Pull Request that modifies the original text to make it more translatable.
+```
+
Crowdsourcing has played a pivotal role in this translation endeavor, harnessing the collective intelligence and linguistic skills of individuals passionate about open science and reproducible research.
By tapping into the wisdom of the crowd, _The Turing Way_ has been able to leverage the knowledge and expertise of a global network, ensuring accurate and contextually relevant translations.
@@ -144,4 +164,4 @@ The benefits of localising and translating _The Turing Way_ are far-reaching.
It not only makes this invaluable resource more accessible to non-English-speaking communities but also fosters a sense of inclusivity, enabling researchers from various cultural backgrounds to engage with best practices and principles in research reproducibility.
The translation of _The Turing Way_ into different languages through crowdsourcing is a testament to the power of collective action and the commitment to open science principles.
-Through the dedication and collaboration of individuals around the world, _The Turing Way_ continues to evolve and thrive as a comprehensive and inclusive resource for the research community, transcending language barriers and fostering a culture of reproducibility on a global scale.
\ No newline at end of file
+Through the dedication and collaboration of individuals around the world, _The Turing Way_ continues to evolve and thrive as a comprehensive and inclusive resource for the research community, transcending language barriers and fostering a culture of reproducibility on a global scale.
From d78f4991ed5334824ad2490a9c3d8f4eb1e415be Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:51 +0000
Subject: [PATCH 084/142] Update source file translation-localisation.md
---
.../community-handbook/translation/translation-localisation.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/book/website/community-handbook/translation/translation-localisation.md b/book/website/community-handbook/translation/translation-localisation.md
index 522a1bcf731..4cccc82a9d9 100644
--- a/book/website/community-handbook/translation/translation-localisation.md
+++ b/book/website/community-handbook/translation/translation-localisation.md
@@ -28,12 +28,13 @@ DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807)
## Examples for Localisation Platforms
-Many open source projects such as [GitLab](https://crowdin.com/project/gitlab-ee), [FreeCAD](https://crowdin.com/project/freecad), [electron](https://crowdin.com/project/electron), [PostgreSQL](https://crowdin.com/project/postgresql), [OBS Studio](https://crowdin.com/project/obs-studio) are localised using different Translation Management System (TMS).
+Many open source projects such as [GitLab](https://crowdin.com/project/gitlab-ee), [FreeCAD](https://crowdin.com/project/freecad), [electron](https://crowdin.com/project/electron), [PostgreSQL](https://crowdin.com/project/postgresql), [OBS Studio](https://crowdin.com/project/obs-studio) are localised using various Translation Management Systems (TMS).
- [Transifex](https://www.transifex.com/)
- [Crowdin](https://crowdin.com/?gclid=CjwKCAiAvriMBhAuEiwA8Cs5ldEGwrOeDJtdY2kneF6vBXx8hYiXD1oJPcWB1SO0VBSTuz60AaDYUhoCj_8QAvD_BwE)
- [Lokalise](https://lokalise.com/)
- [Pontoon](https://pontoon.mozilla.org/)
+- [Weblate](https://weblate.org/en/)
### Features of Localisation Platforms
From dffbe59544d4407bf010fd1bb999ac8d73a2f473 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:52 +0000
Subject: [PATCH 085/142] Update source file translation-workflow.md
---
.../translation/translation-workflow.md | 20 ++++++++++---------
1 file changed, 11 insertions(+), 9 deletions(-)
diff --git a/book/website/community-handbook/translation/translation-workflow.md b/book/website/community-handbook/translation/translation-workflow.md
index 5c2d8022ed1..668e377c680 100644
--- a/book/website/community-handbook/translation/translation-workflow.md
+++ b/book/website/community-handbook/translation/translation-workflow.md
@@ -1,7 +1,7 @@
(ch-translation-welcome)=
-# Welcome to the translation and localisation team of _The Turing Way_!
+# Welcome to the Translation and Localisation Team of _The Turing Way_!
-We are members of The Turing Way community with different motivations to localise the content to different languages.
+We are members of _The Turing Way_ community with different motivations to localise the content to different languages.
Feel free to join the `#translation` channel in [_The Turing Way_ slack](https://theturingway.slack.com).
You will also have to create a Crowdin account but more on that {ref}`in the next section`
The team has a fortnightly call on Tuesdays at 5pm UTC to co-work, discuss, and check the progress of the translation.
@@ -19,6 +19,7 @@ Everyone interested in participating in a translation effort should be able to w
Before starting a translation project, check out the existing languages being translated.
Is the language that interests you in the localisation platform? If it isn't, reach out to the team to create a new translation team.
+You can see the list of language teams and their managers in the project's [Readme](https://turingway.crowdin.com/turing-way#readme/)
If the language team already exists reach out to the team so you can join them.
When starting a new language translation, there are several aspects to consider in terms of the workflow and translation guidelines.
@@ -46,6 +47,7 @@ Make sure you read these guidelines before you start translating for the first t
### Create and update a glossary
We strongly suggest setting a glossary through the localisation platform.
+You can read more about project glossaries in {ref}`Adding terms to the glossary`.
The Carpentries [Glosario](https://glosario.carpentries.org/) and the [Localization Lab glossary](https://www.localizationlab.org/glossaries) are two good examples of such glossaries.
### Share the translation memory of the project
@@ -53,8 +55,8 @@ The Carpentries [Glosario](https://glosario.carpentries.org/) and the [Localizat
In order to facilitate and speed up the translation of a new language, we recommend sharing translation memory with other projects so similar strings can be translated automatically.
_The Turing Way_ project is linked with the translation memory of a previous version translated in Transifex and another translation for [Open Life Science](https://openlifesci.org/) materials in OLS.
-Translation consistency is crucial and can be made easier when TMS is used.
-As soon as you start translating your project, machine learning algorithms engage, and the system shows previous translations for the source words and how often they were used in the project[^1].
+Translation consistency is crucial and can be made easier when the TMS is used.
+As soon as you started translating your project, machine learning algorithms engage, and the system shows previous translations for the source words and how often they were used in the project[^1].
For example, in Crowdin, you can hover over the source words underlined with the light dashed line to see the previous translations formed by the translation consistency feature.
You can also search earlier translations for specific source words using the Search TM tab.
@@ -71,7 +73,7 @@ alt: Checking consistency in Crowdin by hovering over the source words underline
We have teams for each language, so that no one works alone.
Each team can decide roles for their project members.
-In the translation platform, these roles can translate in having different permissions.
+In the translation platform, these roles can translate into having different permissions.
Roles in Crowdin include manager, translator, and proofreader.
- **Manager** – has similar rights as a project owner except for the ability to manage some of the owner's Resources (for instance, configuring MT engines, advanced workflows, and more) and delete projects.
- **Proofreader** – can translate and approve strings.
@@ -92,19 +94,19 @@ DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807)
In each co-working or external session, prioritise those chapters that are outdated or close to completion.
-Check out our {ref}`guidelines` for a list of the priority list.
+Check out our {ref}`guidelines` for a list of the priorities.
# Translation is a continuous process
As _The Turing Way_ content grows, the translated content does too.
-We strongly encourage monitoring the new content and update the translation fork regularly.
-While updates of the translated content might change according to the availability of resources, it is a good practice to:
+We strongly encourage monitoring the new content and updating the translation fork regularly.
+While updates of the translated content might change according to the availability of resources, it is good practice to:
* Set periodical reviews to improve translations
* Update translation guidelines and glossaries
If you have any recommendations for improving the translation guidelines or setting up language-specific rules, contact [the translation and localisation team](https://github.com/the-turing-way/the-turing-way/blob/main/ways_of_working.md).
-We are very eager to improve the workflow and make the _The Turing Way_ a global project accessible to the wider community.
+We are very eager to improve the workflow and make _The Turing Way_ a global project accessible to the wider community.
In the next chapter, you'll be introduced to Crowdin and how we use it to translate _The Turing Way_.
From 62a56d5963bb3a6cd21f76c92f25ecfa18e641e3 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:53 +0000
Subject: [PATCH 086/142] Update source file activism-cultural-change.md
---
.../ethical-research/activism/activism-cultural-change.md | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/book/website/ethical-research/activism/activism-cultural-change.md b/book/website/ethical-research/activism/activism-cultural-change.md
index 5bd48e82269..4f8173d5fd3 100644
--- a/book/website/ethical-research/activism/activism-cultural-change.md
+++ b/book/website/ethical-research/activism/activism-cultural-change.md
@@ -15,6 +15,14 @@ Here, cultural change is defined as inspiring a change in behaviour in persons/o
This section will continue to describe where you will encounter cultural change.
This is followed by short summaries of works on cultural change, written by Adrienne Marie Brown, William and Susan Bridges and John P. Kotter.
+```{figure} ../../figures/culture-shift.*
+---
+name: culture shift
+alt: A black, white, and purple cartoon of scales. On the one side are a lot of objects, with a person buried under the pile and peering out, and on the other side only two objects with a shiny star on them, and someone standing next to them with a smile. Both sides weigh equally. The text says 'time for a cultural shift, we should value reproducibility as much as the amount of papers published.'
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.8169292](https://doi.org/10.5281/zenodo.8169292).
+```
+
(er-activism-cultural-change-when)=
## Where/when will you encounter cultural change?
As your social environment is continuously changing, you are likely to experience some degree of cultural change on a daily basis.
From d990afdbed5f52f4dff25100433fd4c352c2afd2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:53 +0000
Subject: [PATCH 087/142] Update source file activism-env-impact.md
---
.../activism/activism-env-impact.md | 13 ++++++-------
1 file changed, 6 insertions(+), 7 deletions(-)
diff --git a/book/website/ethical-research/activism/activism-env-impact.md b/book/website/ethical-research/activism/activism-env-impact.md
index 0aae5c689fb..57221be6657 100644
--- a/book/website/ethical-research/activism/activism-env-impact.md
+++ b/book/website/ethical-research/activism/activism-env-impact.md
@@ -115,16 +115,15 @@ Energy usage at different times of the day has different carbon intensity. This
The Climate Aware Task Scheduler (CATS)[https://github.com/GreenScheduler/cats] has been built specifically with this in mind. This tool can calculate how much carbon will be emitted during the run of a specific task, look at the carbon emission forecast, and schedule the task to be run at a time when carbon intensity is low.
-```{figure} ../../figures/carbon_computing.*
-
+```{figure} ../../figures/environmental-impact.*
---
-height: 500px
-name: Computing has carbon emissions
+width: 574px
+name: environmental-impact
+alt: Cartoon-like sketch depicting the potential environmental impact of digital research. The illustration is mostly done in a teal blue, with a black cloud in the background, with emissions written across it. On the left, a person sits at a desk with a laptop, with a chatbot and "COMPUTING" text above, symbolizing digital communication. Behind the chatbot lurks three black cogwheels. In the center, "EMISSIONS" emerge from a factory, representing pollution. On the right, a figure throws computers into the ocean, labeled "WASTE", indicating electronic disposal issues.
-alt: Computing has carbon emissions
---
-Computing has carbon emissions illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
-
+Illustration of the potential environmental impact of digital research.
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.8169292](https://doi.org/10.5281/zenodo.8169292).
```
(er-activism-env-impact-data)=
From d6ec0bb7c9ce39f04c0c07789c3464994d8419f2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:54 +0000
Subject: [PATCH 088/142] Update source file activism-unionisation.md
---
.../ethical-research/activism/activism-unionisation.md | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/book/website/ethical-research/activism/activism-unionisation.md b/book/website/ethical-research/activism/activism-unionisation.md
index a00647935b2..92a9a0c3bd2 100644
--- a/book/website/ethical-research/activism/activism-unionisation.md
+++ b/book/website/ethical-research/activism/activism-unionisation.md
@@ -1,6 +1,15 @@
(er-activism-unionisation)=
# Unionisation
+```{figure} ../../figures/unionise.*
+---
+height: 500px
+name: unionise
+alt: A black, white, grey, blue and purple cartoon of three people, one wearing a lab coat and goggles, one in a wheelchair, and one holding a mop, standing hand-in-hand over the purple text 'UNIONISE'. They have speech bubbles above them which say 'Ethics!', 'Open Research!' and 'Working Conditions!'
+---
+
+```
+
(er-activism-unionisation-what)=
## What is a union?
From 565bcea1af367b5c9105731dd4a208e2f58c427d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:55 +0000
Subject: [PATCH 089/142] Update source file data-feminism.md
---
.../website/ethical-research/data-feminism.md | 43 +++++++++++++++++++
1 file changed, 43 insertions(+)
create mode 100644 book/website/ethical-research/data-feminism.md
diff --git a/book/website/ethical-research/data-feminism.md b/book/website/ethical-research/data-feminism.md
new file mode 100644
index 00000000000..06d3b7244fb
--- /dev/null
+++ b/book/website/ethical-research/data-feminism.md
@@ -0,0 +1,43 @@
+(er-data-feminism)=
+# Data Feminism
+
+## Prerequisites
+
+| Prerequisite | Importance | Skill Level | Notes |
+| -------------|----------|------|----|
+| [Data Governance](https://the-turing-way.netlify.app/project-design/data-governance) | Helpful | Beginner | Best practices on how data is collected and managed |
+| [Research Data Management](https://the-turing-way.netlify.app/reproducible-research/rdm#rr-rdm) | Helpful | Beginner | Covers how research data can be stored, described and reused.
+| [Managing Sensitive Data Projects](https://the-turing-way.netlify.app/project-design/sdpm) | Helpful | Beginner | Tips on managing sensitive data.|
+
+
+(er-data-feminism-summary)=
+## Summary
+> 💡 This chapter was written based on the book, [Data Feminism](https://data-feminism.mitpress.mit.edu/) by Catherine D'Ignazio and Lauren F. Klein.
+
+Data feminism is an approach to understanding and practising data science that's informed by the principles of feminist theory. It critiques traditional data practices that often overlook gender biases and other forms of inequality and advocates for a more inclusive, equitable, and reflective practice in data science
+
+Here are some key aspects discussed within the chapter:
+- **Examine Power Structures:** Data Feminism urges a critical examination of power dynamics in data practices. It questions who is represented in data, who benefits from data practices and whose interests are served.
+- **Challenge the Status Quo:** This challenges existing norms in data science, such as the male/female binary and questions other hierarchical classification systems. Thus dismantling stereotypes to promote a more inclusive approach to data.
+- **Inclusivity and Representation:** Data Feminism emphasises the need for diverse representation in data and in data teams. When data science is dominated by a homogenous group, especially those from privileged backgrounds, it risks perpetuating biases and inequalities.
+- **Ethical Considerations and Consent:** Ethical concerns such as consent and privacy are at the core of data feminism. This includes concerns about how data is collected and used and the potential for harm especially to marginalized communities.
+- **Visibility of Labor:** This seeks to recognize and make the often unseen labour in data science visible; especially the contributions of women and people from marginalized groups.
+- **Interdisciplinary Approaches:** Data feminism advocated for interdisciplinary work, drawing insights and methods from various fields outside of traditional data science to enrich understanding and foster more impactful outcomes.
+- **Action and Advocacy:** Beyond analysis, data feminism promotes the need to advocate for change, challenge oppressive structures and promote social justice.
+- **Continual Learning and Adaptation:** Data feminism acknowledges that anti-oppression work is never finished. Continuous learning is essential, and we must recognise society and technology's dynamic nature.
+
+In summary, data feminism is **not just a theoretical framework but a practice** that seeks to reshape how data is collected, analysed and used, focusing on equity, justice and dismantling traditional power structures.
+
+
+(er-data-feminism-motivation)=
+## Motivation and Background
+Data feminism is rooted in the rich history of [feminist activism](https://data-feminism.mitpress.mit.edu/pub/frfa9szd#dyqlckz6ws) and critical theory; it challenges the status quo in data practices by advocating for inclusivity and intersectionality.
+
+Despite advancements, data science still reflects societal biases due to limited data collection and analysis perspectives.
+
+The ethics of data collection, use and interpretation are increasingly under scrutiny. Issues around consent, privacy and the potential harm of data misuse are central to the data feminism discussion.
+
+The impact of biased data practices is global, affecting policies, technology development and social attitudes. These global challenges must be addressed, and data feminism seeks to advocate more inclusive and representative data practices.
+
+
+
From 3fefef169664839b50913676b57c7dbb0778e272 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:55 +0000
Subject: [PATCH 090/142] Update source file data-hazards.md
---
book/website/ethical-research/data-hazards.md | 28 +++++++++++++++++++
1 file changed, 28 insertions(+)
create mode 100644 book/website/ethical-research/data-hazards.md
diff --git a/book/website/ethical-research/data-hazards.md b/book/website/ethical-research/data-hazards.md
new file mode 100644
index 00000000000..b25a623df1e
--- /dev/null
+++ b/book/website/ethical-research/data-hazards.md
@@ -0,0 +1,28 @@
+(er-datahazards)=
+# Data Hazards
+
+
+(er-datahazards-prerequisites)=
+## Prerequisites
+
+| Prerequisite | Importance | Notes |
+| -------------|----------|------|
+| {ref}`er-self-reflection` | Helpful | Reading the self-reflection chapter will give you a good starting point to reflect on your work before applying the Data Hazards labels. This chapter gives more context as to why self-reflection can be a useful tool in your research. |
+
+
+(er-datahazards-summary)=
+## Summary
+
+This chapter will discuss the [Data Hazards Project](https://datahazards.com/), which is a community-developed shared vocabulary of data science risks.
+The vocabulary represents data ethics concepts in the form of Data Hazard labels (which resemble chemical hazard labels).
+These are provided alongside materials to help data practitioners use them, such as templates for workshops or self-reflection.
+
+These labels and materials exist to facilitate interdisciplinary discussions and self-reflection about all kinds of data ethics risks.
+Ultimately, the project aims to help data practitioners to identify and mitigate these risks, by removing barriers for researchers to engage with these practices.
+The chapter describes the motivation behind the project, how you can use it to support your data-intensive work, and how you can contribute to it.
+
+(er-datahazards-motivation)=
+## Motivation
+
+1. **Mitigate risks in your data science work:** we all (hopefully!) want our data science work to do good, but as data scientists we are often trained primarily in solving technical problems, rather than ethical ones. Data Hazards should help you to identify risks that you might not have considered and ways of mitigating those risks.
+2. **Change research culture**: contribute to the wider adoption of data scientists considering the broader ethical implications of their work.
From 688f8118249f4f3a6a39423d08a44576b7ee7288 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:56 +0000
Subject: [PATCH 091/142] Update source file dh-case-study.md
---
.../data-hazards/dh-case-study.md | 292 ++++++++++++++++++
1 file changed, 292 insertions(+)
create mode 100644 book/website/ethical-research/data-hazards/dh-case-study.md
diff --git a/book/website/ethical-research/data-hazards/dh-case-study.md b/book/website/ethical-research/data-hazards/dh-case-study.md
new file mode 100644
index 00000000000..7de5fcfef74
--- /dev/null
+++ b/book/website/ethical-research/data-hazards/dh-case-study.md
@@ -0,0 +1,292 @@
+(er-datahazardscasestudy)=
+# Case Study: Data Ethics and Reproducibility Symposium and Data Hazards Workshop
+We (the organisers: Ceilidh Welsh and Susana Roman Garcia) wanted to create an event that revolved around the Data Hazards framework.
+The event focused on showcasing how different people think about embedding ethics into the work that they do.
+As PhD students, we both felt the need to connect our interest in creating more ethical and reproducible work with our project's scientific questions.
+This passion for working more ethically brought us together, and we sought to see how other people are embedding ethics into their work.
+We hosted talks from PhD students who have been striving to make their work reproducible, how university lecturers might think of implementing Data Hazards into their material, and more (this is available in this {ref}`er-datahazardscasestudy-postevent-githubrepo`).
+We were able to connect with others, share knowledge and learn new skills throughout the process.
+In this chapter, we would like to share with you our experiences, including some of the challenges we faced, and provide tips for people hosting events in the future.
+
+(er-datahazardscasestudy-overview)=
+## Overview
+The Data Ethics and Reproducibility (DER) Symposium was a one-day event held at the Alan Turing Institute on March 10th 2023.
+In total, we had eighteen attendees in person and eighteen attendees online, not including volunteers and hosts.
+This symposium aimed to showcase implementations of reproducibility and ethics for research, with a focus on Data Hazards.
+The symposium structure included a variety of speakers, an interactive workshop and networking opportunities.
+
+A central part of this symposium was the {ref}`Data Hazards` Workshop to provide a collaborative training opportunity for attendees.
+The workshop encourages attendees to explore, discuss and reflect on the ethical implications and wider societal impact of specific data-intensive projects.
+It was an opportunity for attendees to learn how to use the Data Hazards framework and see how it applies to different research projects.
+This allowed attendees to appreciate that ethics is complex, situational and important to discuss in our own contexts.
+
+```{note} **This case study is an account of our first-hand experiences organising and hosting an event. It may be useful to you if you would like to host or organise your own accessible workshop in data ethics and reproducibility (whether a Data Hazards workshop or not).**```
+
+For more detailed information and checklists, please see the Turing Way page for {ref}`Organising a Conference`.
+
+(er-datahazardscasestudy-goals)=
+### DER Symposium Goals
+
+**Primary Goal:** to provide an open, inclusive and accessible space for attendees to learn from one another and discuss first-hand experiences applying ethics and reproducibility to their work.
+we hope to discuss the successes and challenges we might face, and importantly how to consider ethics as more than a tick-box exercise in a research project.
+
+**Goals for Event Organisers:**
+To develop our skills in event management and organisation including:
+- hosting event platforms for attendee registration.
+- questionnaries and polls.
+- learn about accessibility considerations and requirements.
+- equality impact assessments.
+
+Importantly, we wanted to improve our collaborative, teamwork and networking skills with both volunteers and colleagues to provide a curated and thoughtful event.
+
+**Goals for Event Attendees:**
+- Identify areas of research projects where wider ethical implications can be considered in different research contexts.
+- Learn through a hands-on workshop how to embed ethics and reproducibility into current work or research.
+- Discover what other attendees are working on in these areas.
+
+(er-datahazardscasestudy-organising)=
+## Organising the Event
+Here we discuss the logistics for organising an event, from setting up and promoting the event on an external platform to collaborating with volunteers and speakers to help successfully run the event on the day.
+
+(er-datahazardscasestudy-organising-agenda)=
+### Creating an Agenda:
+The first step was to put together some initial ideas for the agenda.
+We worked together using Google Docs.
+We used Google Docs because it allowed us to easily share the documents with other people, and it was easy to access.
+We made sure that no private or sensitive data was in any publicly shared Google Docs.
+Our finalised agenda is [here](https://docs.google.com/document/d/13buQgzAbTTSWVtONXC3cnjegWapJ0CBkL7TBkqNNRqU/edit).
+What did this process look like for us?
+ - brainstorming themed talks,
+ - deciding on keynote speakers,
+ - practicalities of running the [Data Hazards Workshop](https://datahazards.com/contents/materials/workshop.html),
+ - identifying the symposium's target audience,
+ - planning the event start and end times, including rest breaks*,
+ - catering options,
+ - deciding whether to run a hybrid event (online and in-person). Guidelines for hybrid collaboration and events can be found [here](https://the-turing-way.netlify.app/collaboration/hybrid-collab).
+
+*To make the event more accessible, it was important for us to **make sure there were enough 'bio breaks'** to allow people to stretch their bodies, use the toilet and take a breather.
+
+**Speakers**
+A major part of putting together the agenda was all about picking our speakers.
+Speakers are what made our symposium come alive, so we were eager to connect with different people to make sure our event had a mix of perspectives.
+
+When looking for speakers we:
+- reached out directly to keynote speakers whose research area or field considered data ethics and reproducibility.
+- invited speakers from both inside and outside our organisation to include a variety of experiences.
+- asked for abstracts and titles, providing potential speakers with an estimated length of talk (including time for questions) and session they would present in.
+
+
+(er-datahazardscasestudy-organising-advertising)=
+### Advertising the Event
+
+**Choosing a date and gauging interest:**
+Before even asking for funding, we wanted to know if there was enough interest to organise a symposium.
+So we reached out to our community *before beginning to organise* the symposium to gauge interest and spread the word.
+This allowed us to know what other events were going on in The Alan Turing Institute and research field so that we could avoid clashes or busy times of the year.
+
+**Eventbrite:**
+After finding an available date for our interested participants, we chose to advertise our event on Eventbrite.
+At the time of running our event, we could host it for free for 30 participants.
+However, as of now (November 2023), Eventbrite only allows you to host your event for free with up to 25 participants, then it charges you.
+Some alternatives you may use could be [Humanitix](https://humanitix.com/us/pricing), [Lu.ma](https://lu.ma/) or [eventsforce](https://www.cvent.com/uk).
+Because we were running a hybrid event, we created two event pages (one [in-person](https://www.eventbrite.co.uk/e/in-person-data-hazards-ethics-and-reproducibility-one-day-symposium-tickets-516803953537) and one [online-only](https://www.eventbrite.co.uk/e/online-data-hazards-ethics-and-reproducibility-one-day-symposium-tickets-517490858087?keep_tld=1)).
+Eventbrite worked well for us because:
+- it could be accessed by everyone, not just those in our organisation.
+- we could use it to gather participant information (clearly explaining why we were asking for the sensitive information and how the data would be handled), including accessibility information participants wanted to declare and dietary requirements.
+
+**Communications**
+To make sure we kept attendees engaged and up to date, we emailed them before the event to:
+- encourage those who could no longer attend to cancel their reserved slot so that someone else could attend in their place.
+- provide a small nudge and reminder that the event was happening.
+- provide participants a code of conduct and agenda in advance.
+- provide a Zoom link for online participants (one-week in advance) and directions to the location of the symposium for those attending in-person.
+
+This is what a template email could look like:
+
+> Dear Participants,
+> Thank you for registering for the *(In person) Data Hazards, Ethics and Reproducibility One-Day Symposium*, on the *10th March 2023*.
+> We hope you are as excited as we are about this symposium!
+>
+> **Checking in: can you still make it?**
+> We ask you to please be considerate and kindly let us know in advance if you can no longer make it to the event.
+> This will help us reduce waste when ordering catering as well as help with organizing room numbers.
+> Due to the high demand of this event, we have people in a waiting list, so please do cancel your ticket in advance if you cannot make it any more, in order to allow someone else to join instead.
+> Please cancel directly through Eventbrite or by emailing the organisers.
+>
+> **Agenda**:
+> Please find the tentative agenda here (add your own link here). It is mostly set up by now, please keep your eyes open for final details in the coming days. We are looking forward to showcasing these wonderful people and talks.
+>
+> **Code of Conduct**:
+> We ask all attendees to familiarize themselves with the code of conduct for the event (add your own link here). Please do have a read in your own time in order to allow for an open and welcoming environment among all participants.
+>
+> **How to reach the Alan Turing Institute, Enigma room**:
+> Once you arrive to the main Alan Turing Reception area, there will be someone there to greet you and guide you towards the Enigma room.
+> Instructions on how to get to the Turing Institute can be found here (add your own link here).
+
+
+(er-datahazardscasestudy-organising-collaboration)=
+### Collaboration:
+The DER symposium had two primary organisers, however it would not have been possible without the help of different collaborators.
+Here we discuss the steps we took to reach out to volunteers, symposium collaborators and speakers to help the event run smoothly.
+
+**Internal Teams**
+We had several collaborators from within our [organisation](https://www.turing.ac.uk/) including:
+- the **Skills Team** who assisted us with:
+ - completing equity, diversity and inclusion assessment and data protection forms.
+ - understanding the financial requirements of the event, from paying speaker travel expenses to setting up a purchase order for an event caterer.
+ - providing grassroots funding to cover event expenses.
+- the **Facilities Team** who assisted with:
+ - delivery of the catering on the day.
+ - room bookings to host the event.
+ - microphone and audio-visual set-up for the room to host the hybrid event.
+
+**Volunteers**
+Volunteers were an essential part of the day, and our event would not have been successful without their help!
+For clear communication with volunteers, we:
+- **provided an availability form** for volunteers to fill in, indicating specific sessions or hours they could help, what they would like to do, and their own accessibility requirements.
+- **hosted an on-boarding call** to talk through the agenda and highlight the parts of the day where we would require help from volunteers.
+- **created a dedicated volunteer's Slack channel**, so that volunteers could ask questions relating to the event, and we could easily deal with any troubleshooting during the event.
+- [**created a final volunteer's task form**](https://hackmd.io/c2AnZHeRRtWaA_QRwobjsQ), so that all volunteers had been assigned tasks before the event began
+
+
+(er-datahazardscasestudy-organising-catering)=
+### Catering
+For our event we choose a local, entirely vegan caterer, to align with the core values of the event.
+To ensure successful ordering and delivery of the catering on the day we:
+- estimated the number of attendees to provide catering - including volunteers, speakers and organisers.
+- received a quote from the caterers in advance and ensured we had the budget to cover the quote.
+- collected dietary requirements to ensure that all attendees were catered for, and ensured the catering company received these requirements in advance.
+- arranged a delivery time and location.
+- ensured payment to catering company as per company and organisation policies.
+
+Tip: make sure terms and conditions are read and timing requirements from different parties involved are clear from the beginning.
+It might be that the caterer you are ordering from requires a purchase order to be completed at a certain time to complete the order action.
+
+
+(er-datahazardscasestudy-hosting)=
+## Hosting the Event
+There is already a chapter on {ref}`cl-organising-conferences` which includes an in-depth dive into requirements for accessibility.
+Likewise, there is also a section for {ref}`cm-comms-overview-accessibly`.
+As well as on {ref}`cl-hybrid-collab-guidelines`.
+
+From our experience, here are some extra tips on the day of the event.
+
+(er-datahazardscasestudy-hosting-startingevent)=
+### Starting the Event
+- As the hosts arrive in-person at least 1 hour prior to start time to ensure the Zoom link and audio-visual equipment (speakers, screens and microphones) are all working.
+- Open the online call early to allow for:
+ - volunteers to settle in and open any breakout-rooms.
+ - participants to join in advance and set-up break out rooms for networking events and workshops later in the day.
+
+(er-datahazardscasestudy-hosting-hybridevent)=
+### Hybrid Event Tips
+We chose to host the symposium in a hybrid format as this would allow attendance for those interested in the topic, and speakers who would be unable to attend in-person.
+
+There are a lot of tasks involved in running a hybrid event.
+Thanks to good communication with volunteers and preparing the room before the event, our hybrid format ran successfully without hiccups.
+Here we share some tips that helped us!
+
+To ensure a smooth hybrid event, we:
+- tested the physical room audio-visual the day before and the day of the event, to ensure there were multiple microphones and the capability for live Zoom recordings.
+- had in-person session chairs to introduce speakers and make sure people (both online and in-person) kept to agenda timings.
+- made sure session chairs were aware of the hybrid set-up, including microphones, speakers and Zoom settings,
+- made sure that there was always at least one person in the room who was comfortable with the hosting technology.
+- set a non-disruptive 1min warning, using a 1min sign to hold up in-person, or type into the chat online, to signal the end of the talk.
+- kept questions to the end of the talks to avoid disruptions and talks becoming longer.
+- kept in contact with online hosts throughout the day to ensure both the presentations and the audio were working.
+- had our online volunteers keep track of break-out rooms, host discussions, and keep track of questions for Q&A sessions.
+
+
+(er-datahazardscasestudy-hosting-accessibility)=
+### Accessibility
+Below we provide some insight into what was important for us to consider during the event.
+
+**Code of Conduct**
+We put together a code of conduct for the event that reflected our values and the values of the community we aimed to create during the symposium.
+It also summarised the expectations of participants joining the symposium and laid out reporting guidelines and contact points for if the code of conduct was breached during the event.
+
+Please find our code of conduct [here](https://hackmd.io/@7D_si7-qQwKdepUrj7_AzA/DER_CoC).
+
+Additionally, overall, below we highlight some points that we actioned to ensure that the hybrid format and the event were accessible:
+
+- collected accessibility requirements at the time of advertising, to help with planning.
+- used [Otter.ai](https://otter.ai/), a speech-to-text transcription application using artificial intelligence and machine learning.
+ It shows captions for live speakers and generates written transcriptions.
+ Note: Otter.ai is not always sufficient as it has been trained on English and American accents, so further editing of subtitles or transcripts might be needed.
+- ensured all participants in person were using microphones when speaking.
+ Microphones can be helpful for all hearing requirements, both online and in-person (don't assume everyone can hear equally).
+- provided regular accessibility breaks.
+- reminded all participants which sections of the day would be recorded.
+- provided a space for participants to include their names and pronouns using name labels for in-person and Zoom names online.
+- provided a code of conduct, and contact points for if the code of conduct was breached.
+- used the raised-hand function in Zoom for direct questions, but included a session chair to monitor for questions in the chat.
+
+(er-datahazardscasestudy-hosting-workshop)=
+## Hosting a Workshop: Data Hazards
+The Data Hazards workshop was a key part of the symposium.
+Participants engaged with a real-life research case study, presented by the researchers themselves, to evaluate the Data Hazards labels and which ones may apply.
+The researcher gave a five-minute presentation on whole-cell models of _E. coli_.
+Participants could then ask the researcher only factual questions about the project, for example, 'where did you collect your data from?'.
+There was collaboration between attendees, volunteers and the researcher to discuss the ethical context of the project.
+We split the attendees into smaller groups to facilitate discussion and provide a series of prompt questions.
+Each group then labelled the research project with the hazards they thought applied.
+These were then fed back to the researcher for broader group discussions.
+Details of the workshop run on the day are available in the {ref}`er-datahazardscasestudy-postevent-githubrepo`.
+
+(er-datahazardscasestudy-postevent)=
+## Post Event
+Once the event had finished we collected feedback from participants.
+Below we provide information on how we did this.
+
+(er-datahazardscasestudy-postevent-feedbackforms)=
+### Feedback Forms
+To cover all avenues for feedback after the event we:
+- provided a QR code and link to the feedback form in the final session of the day and encouraged participants to complete this form.
+- emailed participants after the event to thank them for their attendance and share the feedback form again.
+- collected slides and recordings from speakers.
+- created a public Git repository where all content is openly available for attendees and those interested in organising and hosting a similar event.
+
+Feedback is really invaluable to ensure that future organisers can learn from previous events.
+In our case, this was our first symposium, so feedback from participants was really important!
+Here we provide some feedback we were given after the event.
+
+**Positive Feedback:**
+- Attendees who came to the symposium with no experience of the data hazards enjoyed the interactive nature of the workshop, saying that: *'the structure of the course made it very easy to follow, and the case study element was very interactive with lots of opportunities to ask questions.'*
+- Attendees also enjoyed the wide applications of data ethics and reproducibility in the research space.
+- Attendees enjoyed networking over lunch, and our [vegan catering](http://yellowkitchen.co.uk/) got lots of compliments!
+
+**Constructive Feedback:**
+- Some attendees struggled with people joining and leaving parts of the online event but recognised this was out of the organiser's control.
+- A consideration for future events would be to create initiatives to encourage people to stay online for the whole day.
+- Attendees felt that an additional industry perspective would have been beneficial.
+
+(er-datahazardscasestudy-postevent-githubrepo)=
+### GitHub Repository
+To embody the topics of reproducibility and open science, we have shared symposium content on a public GitHub repository.
+The aim of this is to help anyone who wants to run a workshop or symposium in the future consider the different elements of event organisation and hosting.
+
+Find our full GitHub repository, including recordings of speakers, code of conduct, and forms [here](https://github.com/Susana465/der_symposium_20230310).
+
+(er-datahazardscasestudy-challenges)=
+## Challenges
+As this was the first event (on this scale!) that we had organised, there were several challenges that popped up throughout the process.
+
+The primary challenge was understanding the number of hours required to organise an event.
+This event took over 50 hours of organisational time over a period of three months, from requesting funding, form writing, code of conduct, creating the event page, advertisement, organising catering and so on.
+If this is the first time you are organising an event, different tasks may take longer than expected to complete.
+We would recommend you establish a large organising committee of passionate people, to work together and split tasks efficiently.
+It is also important to recognise the boundaries and constraints of how long you are willing to spend organising an event.
+Don't let perfection be the enemy of good!
+This also taught us that organising an event will **always** take longer than you expect, so plan accordingly!
+
+(er-datahazardscasestudy-reflections)=
+## Reflections
+After the event, we realised that it is important to understand your organisation's guidelines and frameworks for hosting events, what support they can offer you, and reach out to ask for help where you need it.
+
+In our experience organising and hosting an event was both stressful and fun!
+
+Hosting a hybrid event was challenging and required extra organisation and volunteers.
+But after all the effort we put into it, it ran smoothly and we were very proud to have both online and in-person attendance.
+
+We also recognise the importance of {ref}`self reflection` throughout the process of organising an event, and how our lived experiences gave us a particular lens on how we view the world.
+So ensuring we collaborated with others, and took on different points of view ensured a responsible, inclusive, and fair event!
From 9037a93f2ea9ac88d748e578af185deea79978d1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:56 +0000
Subject: [PATCH 092/142] Update source file dh-how-to-use.md
---
.../data-hazards/dh-how-to-use.md | 114 ++++++++++++++++++
1 file changed, 114 insertions(+)
create mode 100644 book/website/ethical-research/data-hazards/dh-how-to-use.md
diff --git a/book/website/ethical-research/data-hazards/dh-how-to-use.md b/book/website/ethical-research/data-hazards/dh-how-to-use.md
new file mode 100644
index 00000000000..cd8a50add93
--- /dev/null
+++ b/book/website/ethical-research/data-hazards/dh-how-to-use.md
@@ -0,0 +1,114 @@
+(er-datahazardshowtouse)=
+# How to use the Data Hazards project
+
+```{figure} ../../figures/data-hazard.*
+---
+height: 500px
+name: data-hazard
+alt: A cartoon sketch of a female-presenting researcher using the Data Hazard labels on a research project. The first section in the image is the researcher looking at 10 data hazard labels under the heading 'Learn'. An arrow leads to the next step, where under the heading 'Apply' the group of people are looking at a research paper with the researcher and talking to one another, one person is raising a hand to ask a question. An arrow then leads to 'Display' where the researcher is pointing to their paper infront of an audience, with the hazard labels on each side. Learn, Apply and Display are all connected to the bigger title of Reflect, surrounded by a thought bubble. To the right-hand side of the Reflect heading, the researcher and another person are sticking hazard labels to a piece of paper.
+
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
+There are four steps to using the Data Hazard labels:
+
+1. **{ref}`Learning`**: familiarising yourself with the Data Hazard labels.
+
+2. **{ref}`Applying`**: deciding which Hazard labels are relevant to your project.
+
+3. **{ref}`Reflecting`**: on what to do differently and what mitigations to make.
+
+4. **{ref}`Display`**: displaying the labels alongside your work can help you to communicate that you've thought about these broad ethical issues and how you'd like others to use your work.
+
+In addition, whether you have used the labels yet or not, you can also **{ref}`contribute`** to the project. If you think any labels are missing or could be improved, this project is looking to evolve with collaboration.
+
+(er-datahazardshowtouse-learning)=
+## **1. Learning** about the Data Hazard labels
+The first step in using the Data Hazards materials is learning about the Data Hazards labels: familiarising yourself with them so that you can later {ref}`apply` them to a project.
+
+
+Data Hazards labels are supposed to represent as broad a selection of ethical risks associated with data-centric work as possible.
+This includes, but is not limited to the risks considered by {ref}`ethics committees`, which often focus on risks to research participants that could lead to legal repercussions for the research organisation, such as [consent](https://datahazards.com/contents/hazards/lacks-informed-consent.html) and [privacy](https://datahazards.com/contents/hazards/risk-to-privacy.html).
+It also includes issues like [algorithmic bias](https://datahazards.com/contents/hazards/reinforces-biases.html) or [danger of misuse](https://datahazards.com/contents/hazards/danger-of-misuse.html) that might result from downstream outputs of research, rather than the research process itself.
+
+Learning about the Data Hazard labels is usually part of a Data Hazards workshop, but you can also do it independently by:
+
+1. Reading [the labels on the website](https://datahazards.com/labels) - click on each of them for more information!
+
+2. Practicing applying them to a project.
+
+3. Talking about them with other people.
+
+4. [Printing out label cards](https://datahazards.com/_downloads/b92f884790471e61048c5e0fee4dd08e/DataHazards_PrintableCards.pdf) and using them in a workshop.
+
+(er-datahazardshowtouse-apply)=
+## **2. Applying** the Data Hazard labels
+Applying the labels means deciding which labels are relevant to a project.
+There is no prescriptive way to do this.
+However, we suggest one way to go through each label one at a time and decide why or why not it applies to your project.
+
+- **What projects can I apply the labels to?**
+
+We recommend that you apply the labels to your own work unless you've been invited to give feedback on another piece of work.
+
+The labels have been applied to many different types of projects that use data or data-intensive methods.
+Some examples of projects include:
+
+- A predictive model that aims to use machine learning to predict human traits from their genetic mutations.
+
+- A digital humanities project that uses web-scraping and natural language processing to analyse the text of political speeches.
+
+- An NHS data-linkage project to create a new database for researchers to use.
+
+- A modelling project that aims to improve whole-cell models of a bacteria.
+
+Labelling these projects was part of various workshops and is not recorded or shared publicly.
+
+- **When should I apply Data Hazards in my work?**
+
+Data Hazards labels can be applied at any stage in the research life-cycle.
+Ideally, the best time to apply the labels is close to the beginning of the research project, at the same time as you might consider your university ethics process, or {ref}`cm-dif-articles-registered-reports` (you can also pre-register your Data Hazards analysis!).
+However, much of our research builds on itself, so researchers have also found [workshops](https://datahazards.com/contents/materials/workshop.html) useful to reflect and plan what they can do better in follow-up projects.
+
+At the beginning of your workflow, you might want to prepare to avoid certain Data Hazards if you can, and if you can't avoid them because of where your data has come from, you may want to acknowledge this.
+For example, if you have a [sensitive data project](https://the-turing-way.netlify.app/project-design/sdp.html), what Data Hazard labels will apply, and/or what can you do to design your project in a way that avoids certain harms?
+
+As you are collecting and analyzing your data, you might want to iteratively think of the potential Data Hazards that exist in the information you are actively collecting.
+If you have a project where data has already been collected in the past, you can still apply and think of what labels may be relevant to the dataset.
+
+When you are reporting your results, it is recommended you also think of reporting mitigation strategies together with the labels; [see examples of how others have done this](https://datahazards.com/contents/materials/examples.html).
+This would then be helpful for people who see your outputs in the future.
+They can be aware of potential risks as they proceed with the project, and continue to think of solutions to any issues related to the research topic.
+
+(er-datahazardshowtouse-precautions)=
+## **3. Reflecting** on Safety Precautions
+
+This chapter is a good place to read about {ref}`er-self-reflection`, where discussion on identity and positionality, power and privilege, and self-reflection prompts are provided.
+Reflecting on where you stand in your work means you are more likely to see and acknowledge mitigation strategies which can apply to data hazards of your work.
+Likewise, reflecting on the history of where your work has come from may shed light as to how and why some data hazards apply to your work and promote thinking on how to alleviate these later.
+
+Are you using data? Then doing some reflection as suggested above could help you think of what Data Hazards labels you might encounter throughout your project, for example ["ranks of classifies people hazard"](https://datahazards.com/contents/hazards/ranks-classifies.html) or ["risk to privacy"](https://datahazards.com/contents/hazards/risk-to-privacy.html).
+
+A key part of the Data Hazards framework is to reflect on what to do differently.
+Thinking about mitigation strategies means that you suggest ways to prevent risks associated with your work, and if no prevention is possible at present, how to avoid it in the future.
+The point of this is not to think of *all* the possible scenarios on how your work carries or can carry risks, and of *all* possible mitigation measures; but to reflect, acknowledge and promote an awareness about the ethical implications of the work that we do.
+
+(er-datahazardshowtouse-display)=
+## **4. Displaying** the Data Hazard labels
+
+To showcase your reflections and how you have applied the labels, displaying them can help people visualise their importance in your work.
+
+The Data Hazards website has some suggestions and templates on [how to present the labels](https://datahazards.com/contents/materials/presenting.html).
+
+(er-datahazardshowtouse-contribute)=
+## **Contributing** to Data Hazards materials
+
+Additionally, to the steps stated above, the Data Hazard labels are a collaborative effort to create a shared vocabulary that evolves with time.
+If you find that labels are missing, you can suggest a new one yourself.
+Guidelines on how to contribute are laid out in the [contribution section](https://datahazards.com/contents/contribute.html) of the Data Hazard website.
+There are different ways of contributing, either by hosting a workshop on how to apply Data Hazard frameworks, by applying them to your work and sharing this, or by proposing new labels to add to the existing ones.
+
+You can reach the team via a [GitHub discussion post](https://datahazards.com/contents/contribute.html), or by [contacting them directly via email](https://datahazards.com/contents/contact.html).
+
+
From 228dfe648db844e82ce7666dbed7f16729bb4135 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:57 +0000
Subject: [PATCH 093/142] Update source file dh-intro.md
---
.../ethical-research/data-hazards/dh-intro.md | 109 ++++++++++++++++++
1 file changed, 109 insertions(+)
create mode 100644 book/website/ethical-research/data-hazards/dh-intro.md
diff --git a/book/website/ethical-research/data-hazards/dh-intro.md b/book/website/ethical-research/data-hazards/dh-intro.md
new file mode 100644
index 00000000000..f66b804ff52
--- /dev/null
+++ b/book/website/ethical-research/data-hazards/dh-intro.md
@@ -0,0 +1,109 @@
+(er-datahazardsintro)=
+# Introduction to Data Hazards Project
+
+Data Hazards is a community project to develop a shared vocabulary of data science risks (in the form of Data Hazard labels) and materials to help data practitioners use them.
+
+These labels and materials are provided CC-BY licensed on the [Data Hazards website](https://datahazards.com).
+They exist to facilitate interdisciplinary discussions and self-reflection about all kinds of data ethics risks.
+Ultimately, the project aims to help data practitioners to identify and mitigate these risks.
+You can watch a short animation explaining the project below:
+
+
+
+
+
+(er-datahazardsintro-datahazardslabels)=
+## Data Hazards labels
+In this section, we explain the nature of the project.
+Feel free to skip ahead to the next section for more practical guidance on {ref}`how to use the Data Hazards` in your data-intensive work.
+
+### What do they look like? Anatomy of a Data Hazards label
+
+Each label has, as described in the main website:
+
+- **Hazard image**, title, and description which represents and describes the risk.
+- **Examples** to clarify what the hazard covers.
+- **Safety Precautions** things that we would want to see done before the research is deployed.
+
+### Example label: high environmental cost
+```{figure} ../../figures/data-hazard-environmental-cost.*
+---
+height: 250px
+name: data-hazard-environmental-cost
+alt: A red diamond with an image of the earth at the centre. The earth is surrounded by a flame.
+
+---
+_Data Hazards_ project illustration by Yasmin Dwiputri. Used under a CC-BY 4.0 licence. [DOI.](https://doi.org/10.31219/osf.io/hzmyp).
+```
+
+#### Description
+This hazard is appropriate where methodologies are energy-hungry, data-hungry (requiring more and more computation), or use special hardware that requires rare materials. Alternatively, this could also apply to research which outputs high amounts of waste.
+
+#### Examples
+ - Example 1: Wet-lab experiments which create large amounts of single-use plastic waste, for example, pipette tips or petri dishes; or specific chemicals that are harmful to the environment {cite:ps}`Freeland2022`, {cite:ps}`Leak2023`.
+
+ - Example 2: Running big models on High-Performance Clusters can have a big environmental impact with the energy they consume {cite:ps}`alaparthi2020bidirectional`, {cite:ps}`Bender2021`.
+
+#### Safety Precautions
+ - Consider recycling programmes, as well as reducing purchasing and shipping.
+ - To communicate the scale of the issue to other stakeholders, you may want to [convert units of energy into more relatable units](https://calculator.green-algorithms.org/).
+ - Find out if your cloud provider uses renewable energy.
+ - Consider profiling your code, and rewriting it to use less energy.
+ - Consider future work that would reduce the need to use increasingly more resources.
+
+---
+
+### But Why Hazard Labels?
+The Data Hazards framework takes inspiration from the visual nature of chemical hazard symbols, communicating to users the potential outcomes and risks of a project.
+Similarly, to chemical hazards, labelling something as hazardous does not change or reduce its inherent risk.
+However, the visual display of the risk allows the user to make choices based on this knowledge.
+The user can choose to take the necessary precautions to keep themselves, others and their environment safe.
+This also applies to the Data Hazard labels, where if we can identify the risks, we can act accordingly and mitigate possible risks.
+
+
+### Where did they come from?
+There were originally six labels, which were identified through reading data ethics papers at [Data Ethics Club](http://dataethicsclub.com): a fortnightly journal club for data science and ethics.
+Through collecting suggestions [on GitHub](https://github.com/very-good-science/data-hazards), and at conferences and Data Hazards workshops, further labels were suggested and added until we reached the current 11 labels as of November 2023.
+
+### The Hazard labels are versioned
+
+The Data Hazard labels are a living project and will continue to change as we gather more suggestions - for this reason, they are versioned semantically.
+At the time of writing, in `v1.0`, there are 11 Data Hazard labels: you can [explore the Data Hazard labels yourself](https://datahazards.com/labels) on the Data Hazards website.
+
+(er-datahazardsintro-ethicalframeworks)=
+## Ethical Frameworks
+Ethical frameworks can provide a toolkit to help researchers, stakeholders, developers, policy-makers and decision-makers understand what is required and should be considered when engaging in responsible research and innovation.
+Philosophically and socially, ethical frameworks have been considered broadly outside of data science and AI settings and projects.
+
+As not everyone may agree on a shared meaning of research ethics, there are many ethical frameworks available.
+Individuals may adopt and interpret ethical meanings based on unique priorities, personal needs, professional requirements or societal and cultural roles.
+
+Some examples of ethical frameworks that already exist in scientific domains include:
+
+1. Citizen Science and Public and Patient Participation in Research {cite:ps}`Groot2022`
+2. Ethical Framework for Presenting Scientific Results to Policy-Makers{cite:ps}`Schroeder2022`
+3. Five Dimensions of Research Ethics: A Stakeholder Framework for Creating a Climate of Research Integrity {cite:ps}`Dubois2018`
+4. ESRC Framework for Research Ethics {cite:ps}`esrc2010Framework`
+5. Ethics of AI in Education: Towards a Community-Wide Framework {cite:ps}`Holmes2022`
+
+The Data Hazards framework has some similarities to the example frameworks listed above.
+However, the Data Hazards provides an intuitive and visual approach to evaluating and reflecting on risks associated with a research project.
+It allows the dangers to be explicitly stated alongside some mitigation strategies researchers can use to tackle these risks.
+It provides us with a toolkit to facilitate discussions, reflection and decision-making for current and future stakeholders.
+Crucially, it also considers a more holistic view of ethics, not focusing on a specific domain or risk, or separating human-centered ethics from non-human animal or environmental frameworks.
+This toolkit allows for reflection across a spectrum of risks and ethical considerations.
+The Data Hazards framework also provides an open-source approach to an ethical framework, where flexibility and creativity to adapt and develop the framework are strongly encouraged!
+
+(er-datahazardsintro-keyterms)=
+## Key Terms
+Risk and hazard are terms sometimes used interchangeably, but sometimes they can have nuanced specific meanings.
+Certain fields like environmental sciences, engineering or medicine require a clear and consistent use of these terminologies.
+Generally, "hazard" refers to the inherent qualities or characteristics of something that make it potentially harmful.
+It's more focused on the nature of the threat rather than the likelihood of it occurring.
+Whereas "risk" is a term that refers to the likelihood and impact of something happening.
+It's often used in decision-making contexts to evaluate the potential consequences of actions.
From 9731bda78ca1092763a832dc587c545b4d2f81c1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:34:57 +0000
Subject: [PATCH 094/142] Update source file ethics-committees.md
---
book/website/ethical-research/ethics-committees.md | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/book/website/ethical-research/ethics-committees.md b/book/website/ethical-research/ethics-committees.md
index 3d865c9e57a..bfa64b13dda 100644
--- a/book/website/ethical-research/ethics-committees.md
+++ b/book/website/ethical-research/ethics-committees.md
@@ -9,6 +9,15 @@ This is because they can provide ethical oversight to expert researchers who do
This is not to liberate the researcher of their ethical responsibilities -- ultimately, they make the decisions as to how to conduct their work -- but to provide support in respect to these questions.
Whilst there is a great deal of complexity involved in holding individuals accountable in scientific projects, this chapter assumes that RECs seek to improve how science is conducted at large.
+```{figure} ../figures/ethics-committee-with-text.*
+---
+height: 500px
+name: ethics-committee-with-text
+alt: A female-presenting person is walking into a path that leads to somewhere far with mountains. The path starts with a big banner that says “Research Ethics Committee”. At the beginning of the path, there is a male-presenting person with a map, a backpack, glasses and a friendly face looking like they are ready to join the other person to embark on their research ethics committee journey. Next to the first part of the path, there are a couple of booths full of people, one with “Ethics Reviewers”, and another one further down with “Ethics Decision Making” as the title of the booth. These represent the journey one goes through when going through research ethics committee processes.
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
There are many ways a research ethics committee might organise itself.
One common approach is to provide a form for all projects conducted at their institution to undergo ethical appraisal.
Below, we propose five headline questions that an ethics committee might want to know about. For each headline question, we provide:
From 73048ea0f7c5c67e39f76dddb683fc365dded772 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:01 +0000
Subject: [PATCH 095/142] Update source file social-data.md
---
book/website/ethical-research/social-data.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/ethical-research/social-data.md b/book/website/ethical-research/social-data.md
index 65ca8d0d45c..cc501f83d8d 100644
--- a/book/website/ethical-research/social-data.md
+++ b/book/website/ethical-research/social-data.md
@@ -17,7 +17,7 @@ As stated by [Flashpoint](https://flashpoint.io/blog/social-data-enhanced-securi
* Social networks like Facebook and LinkedIn
* Photo and video-sharing networks like Instagram, YouTube, and Pinterest
* Interactive media networks like Snapchat and TikTok
-* Microblogging sites like Twitter and Tumblr
+* Microblogging sites like X (formerly Twitter) and Tumblr
(er-social-data-why)=
## Why do we need ethical considerations while working with social data?
From 5e14de0d6d3a83ff9994dbc89d14df2712961273 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:02 +0000
Subject: [PATCH 096/142] Update source file index.md
---
book/website/index.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/book/website/index.md b/book/website/index.md
index 1b9a5ae1b30..9f6fad1a857 100644
--- a/book/website/index.md
+++ b/book/website/index.md
@@ -26,6 +26,7 @@ alt: The Turing Way project is illustrated as a road or path with shops for diff
---
_The Turing Way_ project illustration by Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807)
```
+## Different Pathways
(welcome-community)=
## Our Community
From c3ea3bab622a8f3f35163138998fa6750fd3b89b Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:04 +0000
Subject: [PATCH 097/142] Update source file bigcode_casestudy.md
---
.../data-governance/bigcode_casestudy.md | 87 +++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 book/website/project-design/data-governance/bigcode_casestudy.md
diff --git a/book/website/project-design/data-governance/bigcode_casestudy.md b/book/website/project-design/data-governance/bigcode_casestudy.md
new file mode 100644
index 00000000000..8cb8687ab8d
--- /dev/null
+++ b/book/website/project-design/data-governance/bigcode_casestudy.md
@@ -0,0 +1,87 @@
+(pd-dg-bigcode)=
+
+# BigCode Data Governance Case Study
+
+```{admonition} Info
+:class: info
+This case study was adapted from the [BigCode Governance card](https://huggingface.co/datasets/bigcode/governance-card) in May 2023.
+Learn more about tools and best practices for data governance activities in the {ref}`Data Governance for the Machine Learning Pipeline ` chapter.
+```
+
+[BigCode](https://www.bigcode-project.org/) is an open scientific collaboration working on the responsible development and use of large language models (LLM) for code, aiming to empower the machine learning and open source communities through open governance.
+Code LLMs enable the completion and synthesis of code, both from other code snippets and natural language descriptions, and can be used across a wide range of domains, tasks, and programming languages.
+These models can, for example, assist professionals and hobbyists with building new LLM applications.
+As part of BigCode, the team created the [StarCoder and StarCoderBase Large Language Models for Code](https://huggingface.co/blog/starcoder).
+
+## Data Collection and Management Plan
+
+### Overview
+The primary training dataset used for the BigCode project is The Stack, which was obtained by gathering public code files, issues, and commits from GitHub.
+For more information on The Stack dataset, visit [this page](https://huggingface.co/datasets/bigcode/the-stack) to request access and view the dataset card.
+To collect Github repositories, they first extracted a list of repositories from [GHArchive](https://www.gharchive.org/) and subsequently cloned all of them using a large CPU cluster.
+They also used the data from GHArchive to extract the Github issues.
+The git commits were gathered from a public BigQuery service.
+Additionally, they collected a dataset of annotations of several kinds of private information on a subset of The Stack to support our privacy risk mitigation efforts.
+
+The legal basis for data collection under fair use and with regards to GDPR and the corresponding case law are still evolving.
+In this context, the data collection and data management plans were carefully crafted with support from leading experts in the open source and legal tech community that participated in the BigCode Legal, Ethics, Governance Working Group in a best-effort approach to reflect current understandings of legal requirements for data collection and management.
+
+The following sections will dive into the details of how the team approached key data governance activities like data collection, data management & opt-out, and data processing.
+
+### Data Collection
+
+The StarCoder model was trained on The Stack v1.2, which exclusively contains 6.4TB of permissively licensed data from GitHub repositories, processed from an original source dataset of 102TB.
+Selecting repositories based on licenses is only the first step, however, so this approach is complemented by also giving repository owners the ability to opt out of having their repositories included in The Stack, described further in the Data Management & Opt-out section.
+- **Data selection**: One of the goals of BigCode is to give developers agency over their source code and let them decide whether or not it can be used to develop and evaluate LLMs.
+ Software developers typically rely on licenses to express how they want their work to be re-used.
+ In particular, developers who choose Open Source licenses often do so because they want their code to be broadly re-used.
+ This motivated us to start by selecting data from repositories that met the following criteria:
+ - The repository has an open source license attached - open source, while chosen for very different reasons by different people, typically indicates a willingness to have one's work reused or adapted
+ - The license does not have an attribution clause - attribution is a difficult technical problem for code LLMs.
+ Since they cannot guarantee that the model will be used in a way that attributes its generations to specific training data in a way that satisfies the intent of the licensor, they chose to only keep licenses without an attribution clause
+- **Data updates**: For as long as the BigCode team is maintaining The Stack dataset, they will provide regular updates to the dataset to remove data that has been flagged since the last version.
+ This includes data that has been opted out, and data that was flagged as containing PII, malicious code or using a non-permissive license since the previous release.
+ The current plan is to update the dataset every 3 months, although the schedule may change based on the volume of requests received.
+ If the team is no longer in a position to continue maintaining the dataset, they plan to stop distributing it in its current format and update its terms of use to limit its range of applications further.
+
+### Data Management & Opt-Out
+
+#### Data Access
+- **What data can be accessed**: the 6.4TB of processed data can be accessed through the Hugging Face Hub, while the original 102TB are only accessible to the stewards of the project for the purposes of enabling the research and to support future internal and external requirements that may arise, for example to search the full dataset to recall licenses, determine code provenance, and attribution.
+- **Conditions for data accesss**: users are able to inspect the dataset via the [Dataset Card](https://huggingface.co/datasets/bigcode/the-stack#dataset-card-for-the-stack), but are required to agree to the Terms of Use for The Stack before being able to download it.
+ This includes the requirements to:
+ 1. abide by the terms of original source code licenses, including attribution clauses when required (The Stack provides provenance information for each data point)
+ 2. agree to update copies of The Stack to the most recent usable version specified [here](https://huggingface.co/datasets/bigcode/the-stack/discussions/7)
+ 3. include the Terms of Use and require users to agree to it if a copy is to be hosted, shared, or otherwise provided.
+ As of May 3, 2023, The Stack had been downloaded 50,200 times
+
+#### Data Opt-Out
+- **How a data subject request that their data be removed:** Developers that find that their data is in The Stack by using the [Am I In the Stack? website](https://huggingface.co/spaces/bigcode/in-the-stack) can use a custom link that automatically generates an issue in the BigCode opt-out repository for an official opt-out request.
+ You can choose which repos you’d like to remove, as well as your commits and issues. After submitting the issue, your request is added to the queue for removal from all future iterations of The Stack.
+ Additionally, anyone who is concerned about specific data they have encountered in The Stack, for example relating to PII, malicious code, or code that has an incorrect license or attribution can email contact@bigcode-project.org.
+At the time of the data processing for the StarCoder model training, 44 people had opted out of The Stack and associated repositories were removed.
+
+### Data Processing
+
+One significant concern with respect to privacy was the risk that the code LLM may generate private information found in its training data, including private tokens or passwords matched with identifiers or email addresses.
+Additionally, while users can (and have) requested that data be removed from The Stack dataset because it contains personal data, removing specific information from trained model weights after the fact remains an open technical challenge.
+In order to minimize this risk, they chose to apply automated PII redaction at the pre-processing stage during training.
+
+The PII redaction process consisted of the following steps:
+- **Creating an annotated dataset for PII:** they found that neither regular expression-based approaches nor existing commercial software for PII detection met our performance requirements.
+ In doing so, they aimed to balance the constraints of costs (fair compensation), time (the timing and time to complete the work was on the critical path for the project), and quality (to ensure that PII Detection Model training was not impacted).
+- **Collaborating with crowd-workers in a responsible way:** While traditional data annotation services using salaried employees were considered, they decided to work with crowd-workers through Toloka after reviewing several service providers and their compensation practices - and finding that most would not provide sufficient transparency and guarantees about worker compensation.
+ We selected pay and eligible countries of crowd-workers to ensure that:
+ - Absolute hourly wage was always higher than the US federal minimum wage ($7.30)
+ - Hourly wage was equivalent to the highest state minimum wage in the US in terms of purchasing power parity ($16.50 at the time of writing)
+- **Training a PII detection model:** We engaged 1,399 crowd-workers across 35 countries in annotating a diverse dataset for PII in source code.
+ Our PII detection model, trained on 22,950 secrets, achieves 90% F1 score surpassing regex-based tools, especially for secret keys.
+ The PII annotations are available to approved individuals, and researchers and developers that are granted access are expected to uphold ethical standards and data protection measures.
+ By making it accessible, our aim is to encourage further research and development of PII redaction technology.
+
+Learn more about the PII redaction process through this [blog post from Toloka](https://toloka.ai/blog/bigcode-project/).
+
+## Acknowledgments
+
+This case study is based on the BigCode Governance card, thanks to the efforts of the [hundreds of BigCode participants](https://huggingface.co/bigcode), a living document that will evolve over time with the BigCode project.
+Please leave any comments in the [HuggingFace Community space](https://huggingface.co/datasets/bigcode/governance-card/discussions) to ask a question or start a conversation about BigCode project governance.
From 7d6a3538a6364a46cb980d0308809fdf11aa9d1e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:05 +0000
Subject: [PATCH 098/142] Update source file pd-checklist.md
---
book/website/project-design/pd-checklist.md | 69 +++++++++++++++++++++
1 file changed, 69 insertions(+)
create mode 100644 book/website/project-design/pd-checklist.md
diff --git a/book/website/project-design/pd-checklist.md b/book/website/project-design/pd-checklist.md
new file mode 100644
index 00000000000..8cb9b501cdc
--- /dev/null
+++ b/book/website/project-design/pd-checklist.md
@@ -0,0 +1,69 @@
+(pd-checklist)=
+# Getting Started Checklist
+
+We can begin the project design process by identifying different parts of our research, such as main research questions, methods and materials, code and data requirements, workflow, communication channels, ways of working, collaborative practices, and so on.
+This process allows us to be intentional from the start to ensure that our research is reproducible, well-communicated, and inclusive of all stakeholders where decisions are collaboratively made.
+We can explore and select the right tools and methods for reproducibility in our research and promote good practices such as documentation, version control, peer-review processes, testing, workflow, archiving, and data management plans from the beginning.
+Finally, we can plan for publishing and sharing research components before, during, and after the project.
+
+**Below is a checklist you can use to help identify areas of project planning you might want to look at.**
+
+## Aims & Values
+* Define the main research questions and objectives.
+* Identify the core values and principles that guide your project.
+* Useful documentation: [project canvas](https://canvanizer.com/new/project-canvas), [values document](https://rebelsguidetopm.com/what-are-your-project-values/), [project 1-pagers](https://www.smartsheet.com/content/project-report-templates).
+
+## Timeline & Milestones
+* Establish a project timeline with key milestones, output, and deadlines.
+* Break down the project into manageable phases or tasks.
+* Useful documentation: [Gantt charts](https://clickup.com/blog/gantt-chart-project-templates/), [roadmaps](https://www.smartsheet.com/free-product-roadmap-templates-smartsheet), or [project boards](https://teamhood.com/project-management/project-board/).
+
+## Methodology
+* Determine the appropriate research methods and materials.
+* Consider the necessary code and data requirements for your project.
+* Document the workflow for data collection, analysis, and interpretation.
+* Define data governance processes to ensure data is kept securely, used appropriately, and complies with data regulations in relevant countries/geographic areas.
+* Useful documentation: [data management plan](rr-rdm-dmp), [code repository](pd-project-repo), [electronic lab notebooks](rr-open-notebooks), [Data Governance Chapter](pd-dg)
+
+## Operations
+* Confirm the budget and any funding policies you need to follow.
+* Establish ways of working and collaborative practices for the project team.
+* Identify roles and responsibilities within the project team, using the RACI (responsible, accountable, consulted, informed) matrix or the MOCHA (manager, owner, consulted, helper, approver) matrix.
+* Complete any institutional processes for project setup, such as ethics approval or contract signing.
+* Useful documentation: [RACI matrix](https://project-management.com/understanding-responsibility-assignment-matrix-raci-matrix/), [MOCHA matrix](https://www.managementcenter.org/resources/assigning-responsibilities/#main), [risk register](https://asana.com/resources/risk-register), [project charter](https://www.projectmanager.com/blog/project-charter).
+
+## Stakeholders
+* Identify all individuals, groups, or organizations that have an interest or influence in the project. This includes both internal and external stakeholders.
+* Create a visual representation or matrix to understand the relationships between stakeholders and the project. Map their level of engagement, influence, and interest at each stage of the project. This helps prioritise engagement efforts and tailor communication strategies accordingly.
+* Utilise the ["Facilitating Stakeholder Engagement"](cl-stakeholder-engagement) chapter for guidance and template resources.
+* Useful documentation: stakeholder register, stakeholder map, stakeholder analysis matrix, [personas](pd-persona).
+
+## Community
+If you are intending to build a community for your project or to support participatory research, make a plan!
+* Contact communities from your stakeholder mapping and invite them to discusss the project and goals during planning.
+* Agree decision making processes for the project involving the community.
+* Plan contribution pathways for new participants, establish guidelines for new content, and how you will grow a sense of community.
+* Useful documentation: [Code of Conduct](ch-coc), [Contributing Guidelines](cl), [READMEs](https://the-turing-way.netlify.app/collaboration/github-novice/github-novice-firststeps.html?highlight=readmes), [governance documentation](er-ethics-open-source-governance), [Research Community Managers](cl-infrastructure-community-managers), [GitHub repo for Research Community Management resources](https://github.com/alan-turing-institute/open-research-community-management)
+
+## Outputs
+* Plan for the different outputs of your research, such as publications, software, or datasets.
+* Consider licensing and copyright issues for sharing your outputs.
+* Determine how you will manage intellectual property and ownership rights using an IP register.
+* Remember to include any required reporting to funders.
+* Useful documentation: IP register, [licensing](rr-licensing) and copyright statement, [data management plan](rr-rdm-dmp).
+
+## Communications
+* Identify the target audience for your research.
+* Plan what you want to communicate to your audiences, when you want or need to share progress or results, and the best channels or mediums to do this.
+* Consider open and inclusive practices to involve stakeholders in decision-making.
+* Useful documentation: [The Turing Way Guide to Communication](cm-comms-overview), communication plan.
+
+## Maintenance & Archiving
+* Develop a plan for the long-term maintenance and sustainability of your project.
+* Establish procedures for data management, including storage, backup, and access.
+* Consider archiving your project's artifacts and documentation for future reference.
+
+### Reporting & Evaluation
+* Define how you will judge your project a success (outputs produced, people engaged, milestones reached).
+* Define when you will review these metrics and what the criteria is for changing them.
+* Document and understand any external requirements for reporting such as format, timeframe, type, and audience.
From d89fdf1255ce131556babe6c3e65b3e4b4e9946f Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:05 +0000
Subject: [PATCH 099/142] Update source file pd-overview.md
---
book/website/project-design/pd-overview.md | 32 ++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/book/website/project-design/pd-overview.md b/book/website/project-design/pd-overview.md
index 564a72c2494..28e7aba8fcc 100644
--- a/book/website/project-design/pd-overview.md
+++ b/book/website/project-design/pd-overview.md
@@ -38,3 +38,35 @@ We invite you to contribute to this chapter by adding important tools or practic
```
In the different subchapters we discuss how you can {ref}`start planning` for project design, the {ref}` communication and collaboration` aspect for ensuring reproducibility, {ref}`tools and methods` for reproducibility, {ref}`version control and documentation` aspects and {ref}`sharing your research`.
+
+(pd-overview-mistakes)=
+## Learning from Mistakes
+
+> “Building takes many, many mistakes.”
+> ― Becky Chambers, [The Long Way to a Small, Angry Planet](https://www.goodreads.com/work/quotes/42270825)
+
+Learning about past design mistakes can give us insight into what we can do differently in the future.
+We asked a group of researchers to share what they consider their project design regrets, which we have summarised here:
+
+- Not advocating for clearer goals and success criteria from the beginning.
+- Not communicating the project vision clearly/often enough to the other team members.
+- Not ensuring that all stakeholders were fully aware of the nature of the project.
+- Not understanding that project design is about people first. Designs motivate stakeholders and allow collaboration and inclusion.
+- I guess I wrote these as actions I wish I had done better - Not setting short- and long-term milestones, communicating and enforcing norms for collaborator engagement, delegating work and project management tasks.
+- Not having documentation besides final reports. When being asked about the code or dataset (raw and process), step by step process from preparing data to getting the results, lack of documented guidance in one place made it hard to trace the project with all team members (classic problem).
+- Not properly taking into account the degree to which requirements will change throughout a project - which happens a lot in academia - and the effect this has on designs that then also need to change.
+- Trying to plan too much at the beginning and never getting started.
+- Feeling like I am always taking an ad hoc approach to planning a project and then feeling like I am spending too much time on the organisation side of the project because I don’t have a set workflow to handle project planning and design. Also, not knowing how project planning fits into project design.
+- Using a very messy excel to store/process data, the shame!
+- Over-engineering a design for features that didn’t end up being implemented (in life before academia!)
+- Not implementing Git flow from the start, and not teaching collaborators how to use Git flow.
+- Not developing tests until after a significant amount of code was written.
+- Not doing code reviews.
+- Not defining use scenarios for the software from the beginning, meaning we didn’t pay enough attention to data input and output.
+- Agonising too long before switching to objectively better design (particularly translating from a largely functional codebase to more object-oriented).
+- Going with options that team members are ‘comfortable’ with (for example, using outdated languages or platform-dependent compilers), rather than teaching team members new skills. Makes life more difficult in the long run.
+- Defining governance at different stages of the project or potential scenario planning for how governance might change as the project scales up/down/gains new users and so on.
+- Not thinking about community from the start, starting with a Code of Conduct, thinking about a Contributor License Agreement (intellectual property), what processes will be used and how they will work, how they will impact future contributors and the overall project.
+
+_This section summarises participants' notes from a short workshop called "Good Practices for Designing Software Development Projects (The Turing Way)" at the [Collaboration Workshop 2021](https://www.software.ac.uk/cw21) hosted by [Software Sustainability Institute](https://www.software.ac.uk). The workshop was delivered by Malvika Sharan, Emma Karoune and Batool Almarzouq on 31 March 2021. Zenodo. DOI: [10.5281/zenodo.4650221](https://doi.org/10.5281/zenodo.4650221)._
+
From d70decc8bd996592c028b7497e7b7d15ede8ef33 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:06 +0000
Subject: [PATCH 100/142] Update source file pd-overview-planning.md
---
.../pd-overview/pd-overview-planning.md | 68 +++----------------
1 file changed, 8 insertions(+), 60 deletions(-)
diff --git a/book/website/project-design/pd-overview/pd-overview-planning.md b/book/website/project-design/pd-overview/pd-overview-planning.md
index 3b2e328619c..685c04c2979 100644
--- a/book/website/project-design/pd-overview/pd-overview-planning.md
+++ b/book/website/project-design/pd-overview/pd-overview-planning.md
@@ -8,6 +8,13 @@ In addition, planning your project at the start can help you make sure that you
A human-centered approach in the context of the research project can lead to a better development process, maintenance, and future extension of our work. Furthermore, it will help improve the quality of future project design as we can learn lessons from what worked and what can be improved.
+```{note}
+**Top three 'selfish' reasons to use project design practices**
+1. **Saves time**: once the project is designed and all the connections between different parts of research can be organized with little effort.
+2. **Makes your research openly available**: having your research open from the start can help others working in similar subjects or starting research.
+3. **Get people interested**: you can get people to help you from the start since your project is documented and is easy to share.
+```
+
(pd-overview-planning-expectation)=
## Setting Expectations Explicitly
@@ -17,58 +24,6 @@ It also requires researchers to explore the possible outcomes, plans to address
Project design practices help all stakeholders to be certain about their roles and responsibilities, skill requirements, environment, and research setup they want to create for their collaborators, values they want to promote, and how they can achieve their goals collaboratively.
-(pd-overview-planning-started)=
-## Getting Started Checklist
-
-We can begin the project design process by identifying different parts of our research, such as main research questions, methods and materials, code and data requirements, workflow, communication channels, ways of working, collaborative practices, and so on. This process allows us to be intentional from the start to ensure that our research is reproducible, well-communicated, and inclusive of all stakeholders where decisions are collaboratively made. We can explore and select the right tools and methods for reproducibility in our research and promote good practices such as documentation, version control, peer-review processes, testing, workflow, archiving, and data management plans from the beginning. Finally, we can plan for publishing and sharing research components before, during, and after the project. **Below is a checklist you can use to help identify areas of project planning you might want to look at.**
-
-### Aims & Values
-* Define the main research questions and objectives.
-* Identify the core values and principles that guide your project.
-* Useful documentation: [project canvas](https://canvanizer.com/new/project-canvas), values document, [project 1-pagers](https://www.smartsheet.com/content/project-report-templates).
-
-### Timeline & Milestones
-* Establish a project timeline with key milestones and deadlines.
-* Break down the project into manageable phases or tasks.
-* Useful documentation: [Gantt charts](https://clickup.com/blog/gantt-chart-project-templates/), [roadmaps](https://www.smartsheet.com/free-product-roadmap-templates-smartsheet), or [project boards](https://teamhood.com/project-management/project-board/).
-
-### Methodology
-* Determine the appropriate research methods and materials.
-* Consider the necessary code and data requirements for your project.
-* Document the workflow for data collection, analysis, and interpretation.
-* Useful documentation: [data management plan](rr-rdm-dmp), [code repository](pd-project-repo), [electronic lab notebooks](rr-open-notebooks).
-
-### Operations
-* Confirm the budget and any funding policies you need to follow.
-* Establish ways of working and collaborative practices for the project team.
-* Identify roles and responsibilities within the project team, using the RACI matrix.
-* Complete any institutional processes for project setup, such as ethics approval or contract signing.
-* Useful documentation: [RACI matrix](https://project-management.com/understanding-responsibility-assignment-matrix-raci-matrix/), [risk register](https://asana.com/resources/risk-register), [project charter](https://www.projectmanager.com/blog/project-charter).
-
-### Stakeholders
-* Identify all individuals, groups, or organizations that have an interest or influence in the project. This includes both internal and external stakeholders
-* Create a visual representation or matrix to understand the relationships between stakeholders and the project. Map their level of engagement, influence, and interest at each stage of the project. This helps prioritise engagement efforts and tailor communication strategies accordingly.
-* Utilise the "Facilitating Stakeholder Engagement" chapter for guidance and template resources.
-* Useful documentation: stakeholder register, stakeholder mapping, stakeholder analysis matrix, [personas](pd-persona).
-
-### Outputs
-* Plan for the different outputs of your research, such as publications, software, or datasets.
-* Consider licensing and copyright issues for sharing your outputs.
-* Determine how you will manage intellectual property and ownership rights using an IP register.
-* Remember to include any required reporting to funders.
-* Useful documentation: [The Turing Way Guide to Communication](cm-comms-overview) IP register, [licensing](rr-licensing) and copyright statement, [data management plan](rr-rdm-dmp).
-
-### Community & Communications
-* Identify the target audience for your research.
-* Plan for effective communication and engagement with the community.
-* Consider open and inclusive practices to involve stakeholders in decision-making.
-* Useful documentation: [Code of Conduct](ch-coc), [Contributing Guidelines](cl), [READMEs](https://the-turing-way.netlify.app/collaboration/github-novice/github-novice-firststeps.html?highlight=readmes), communication plan, stakeholder mapping, [governance documentation](er-ethics-open-source-governance).
-
-### Maintenance & Archiving
-* Develop a plan for the long-term maintenance and sustainability of your project.
-* Establish procedures for data management, including storage, backup, and access.
-* Consider archiving your project's artifacts and documentation for future erence.
-
(pd-overview-planning-ethics)=
## Getting Ethical and Legal Approval
@@ -87,19 +42,12 @@ Obtaining ethical and legal approval is a crucial step in the project to ensure
The {ref}`Research Ethics Committees Processes` chapter provides more information about each item. Refer to other chapters in the {ref}`Guide for Ethical Research` for further guidance.
```{warning}
-Even if you do not need institutional ethical approval, your project will still benefit from planning using self-relfection techniques and including ethical considerations in the project design.
+Even if you do not need institutional ethical approval, your project will still benefit from planning using self-reflection techniques and including ethical considerations in the project design.
Ethics should not be tied to institutions, it is everyone's responsibility.
```
## Organising Files and Documents
-```{note}
-**Top three 'selfish' reasons to use project design practices**
-1. **Saves time**: once the project is designed and all the connections between different parts of research can be organized with little effort.
-2. **Makes your research openly available**: having your research open from the start can help others working in similar subjects or starting research.
-3. **Get people interested**: you can get people to help you from the start since your project is documented and is easy to share.
-```
-
Create a shared repository to allow easy access to information and different documents related to your project.
A project repository can be openly available if you are developing an open source project, or can be shared only with your collaborators.
In the chapter {ref}`pd-project-repo`, you can learn about how to set up a repository with key documents like a landing page, contribution guidelines and communication pathways.
From a75c8879c43675aebd34c8a85fe899f0eef12d4c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:06 +0000
Subject: [PATCH 101/142] Update source file pd-overview-repro.md
---
.../pd-overview/pd-overview-repro.md | 59 ++++++++++++++-----
1 file changed, 43 insertions(+), 16 deletions(-)
diff --git a/book/website/project-design/pd-overview/pd-overview-repro.md b/book/website/project-design/pd-overview/pd-overview-repro.md
index aa8f1d1f9cc..aeaa8b56ddf 100644
--- a/book/website/project-design/pd-overview/pd-overview-repro.md
+++ b/book/website/project-design/pd-overview/pd-overview-repro.md
@@ -1,5 +1,5 @@
(pd-overview-repro)=
-# Communication and Collaboration
+# Collaborative project documentation
Good communication and collaboration practices are complementary to research reproducibility, and often it is hard to separate these concepts from each other.
In _The Turing Way_, we consider these essential for reproducible research and provide separate guides for {ref}`communication` and {ref}`collaboration`.
@@ -7,38 +7,63 @@ In _The Turing Way_, we consider these essential for reproducible research and p
In this page, we highlight some of the most important recommendations for collaboration and communication to ensure that you, and everyone else in your project, understand what the project is about, who the stakeholders are and how they can participate.
You can visit specific chapters to gain an in-depth understanding and selection of practices that meet the specific requirements in your project.
-**Documenting project plans and processes for transparency**:
+## Minimal documentation
-Document all proposed plans for the project with information on available resources and recommended practices to ensure everyone is on the same page (literally!).
-Communicate the work culture that you want to promote and policies that ensures the safety and security of both your data and people.
+Your open source project should at a minimum provide a license together with a README file with all the basic, general information a newcomer needs to get oriented.
+The license to apply will depend on your type of research output (text, data, software, hardware, reagents to name a few).
+See the license chapter {ref}`rr-licensing`
+It should contain a **recognizable name** for your project, as well as a **declaration of the licensing terms** under which it may be distributed (see the {ref}`rr-licensing-hardware` chapter).
Documentation should be shared via centralised, findable and accessible platforms.
-It is particularly important to share the vision, mission and milestones clearly.
+
+## Documenting project plans and processes
+
+Document the **current state**, **ongoing development**, and/or any **future plans** for the project.
+Add information on available resources and recommended practices to ensure everyone is on the same page (literally!).
+It may also be important to make it clear what your project is not meant to be.
+
+In addition to the above, it is interesting to document the *principal need* for your project, especially for software and hardware project: what problem are you trying to solve ?
+That includes a **problem description** of whatever issue sparked the project, a **functional description** of how your project is meant to address it, and a **context description** of the users and environment your project is targeting.
+
+It is particularly important to share the **vision, mission, and milestones** clearly.
Provide sufficient information for what the expected outcomes and deliverables are.
+
Provide overarching as well as short-term goals and describe expected outcomes to help contributors move away from focusing on a single idea of the feature.
Describe the possible expansion of features in pre-determined and agreed on ways at stages beyond the initial implementation.
-**Project's "Who-is-Who"**:
+## Project's "Who-is-Who"
+
+Include a **list of contributors**, **contribution guidelines**, and information on **contact points** where to ask for help.
+In addition,
+- Create an overview of the putative "personas" {ref}`pd-persona` (people and organisations) and how they may interact with the project.
-Create a directory to highlight the different stakeholders with their roles in the project, keys skills, interests and contact information (when possible).
Describe what opportunities for collaboration different members will have.
When possible, such as in an open source project, provide these details for those outside the current group, especially when you want to encourage people outside the project to be involved.
+Communicate the work culture that you want to promote and policies that ensures the safety and security of both your data and people.
-Provide resources on ways of working to ensure fair participation of stakeholders who collaborate on short- and long-term milestones within the project.
-It reduces or addresses concerns about the project's progress towards meeting goals and prevents potential fallout between project stakeholders.
-**Participation and contribution process**:
+Provide resources on ways of working to ensure fair participation of contributors who collaborate on short- and long-term milestones within the project.
+It reduces or addresses concerns about the project's progress towards meeting goals and prevents potential fallout between project contributors.
+
+## Participation and contribution process
+
+ In order to make your project discoverable, you may add a machine-readable metadata file, such as an [Open-Know-How manifest](https://www.internetofproduction.org/openknowhow).
Considering the variety of different backgrounds and skills your members bring, describe how they can participate and start contributing.
-Provide clear opportunities for contributions, review, management, mentoring and support.
+You should also **think about your audience**. Your project might be reused by people with different skills, roles, objectives, and socio-economic and cultural environments.
+
+
+Provide clear opportunities for contributions, review, management, mentoring, and support.
Provide an overview of how different contributions or resources are connected and how new contributions will fit into existing materials.
+You may also include an index of all the project's documentation, so people can easily find what they are looking for.
+
Provide a decision-making framework to facilitate discussions and reaching a shared conclusion.
-In the context of software, coding projects are as much about communication as they are about coding (if not more).
+In the context of software and hardware, open source projects are often as much about communication as they are about coding or building (if not more).
Allow informed discussions when a particular project design has reached the end or when it is useful to update it for efficiency and sustainability.
-Describe how your research objects are available or will be published and how different stakeholders will be recognised.
-It helps everyone feel appreciated and acknowledged for their contribution to the overall vision.
+Describe how your research objects are available or will be published and how different contributors will be recognised.
+It helps when everyone feel appreciated and acknowledged for their contribution to the overall vision.
-
+
### Preparing for Change
@@ -91,7 +118,7 @@ We asked a group of researchers to share what they consider their project design
**I work alone, do I need to think about project design?**
The short answer is 'yes'.
-The project design will allow you to manage your work well for yourself (see the section: {ref}`Getting Started`).
+The project design will allow you to manage your work well for yourself (see the section: {ref}`Getting Started Checklist`).
A little work and time investment early on in project design saves a lot of time later when any circumstances arise that demand change.
```
From b1b462fa7be29c1d6b4ccbd4d0d75dc6714eef8e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:08 +0000
Subject: [PATCH 102/142] Update source file persona-contributors.md
---
.../project-design/persona/persona-contributors.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/book/website/project-design/persona/persona-contributors.md b/book/website/project-design/persona/persona-contributors.md
index 17926bab5e0..092867eb3d8 100644
--- a/book/website/project-design/persona/persona-contributors.md
+++ b/book/website/project-design/persona/persona-contributors.md
@@ -47,7 +47,7 @@ They are passionate about open data and using data for good, but also understand
They attend data science meetups in the city but are interested in finding a community working towards improving how research is conducted.
They have experience with GitHub and contributing to open projects.
-1. **Discovery** - Alia first hears about _The Turing Way_ via Twitter ([#TuringWay](https://twitter.com/search?q=%23TuringWay&src=typed_query)).
+1. **Discovery** - Alia first hears about _The Turing Way_ via X (formerly Twitter) ([#TuringWay](https://twitter.com/search?q=%23TuringWay&src=typed_query)).
2. **First Contact** - They land on the project's README and look for the contributing guidelines to see where their skills can be applied.
3. **Participation** - They find an issue asking for help on writing the Credit for Reproducible Research chapter and add a few paragraphs on how to properly cite research software.
4. **Sustained Participation** - After constructive feedback and collaboration with _The Turing Way_ team, Alia follows the community on social media and attend the online Collaboration Cafe.
@@ -61,7 +61,7 @@ They are always looking for opportunities to share their expertise, particularly
They are very keen to collaborate with people and to volunteer their time for collaboration projects.
They like seeing their work make an impact and are keen to know about the eventual result of their collaborations.
-1. **Discovery** - Amal finds out about _The Turing Way_ book from the Twitter feed of experts in reproducible research who they follow.
+1. **Discovery** - Amal finds out about _The Turing Way_ book from the X feed of experts in reproducible research who they follow.
2. **First Contact** - Amal navigates to the GitHub repository and reads the content there over a couple of days. While reading, they make notes on areas they could add to from their research.
3. **Participation** - They compile their work into a chapter format and submit it to the repo.
4. **Sustained Participation** - Amal checks back frequently to look at feedback on their chapter and respond to it. In their spare time, they make suggestions and edits on other chapters.
@@ -74,7 +74,7 @@ Noor is a final-year PhD student who has their dissertation deadline coming up.
They are feeling the pressure of needing to write up the results of their research but finding it easy to procrastinate.
They are confident that their research has taught them some particular considerations for reproducible environments, but they are slightly intimidated by the expertise of other people in their field, and they are considering their future after their PhD.
-1. **Discovery** - Noor comes across _The Turing Way_ when they're surfing Twitter while trying to write up their research.
+1. **Discovery** - Noor comes across _The Turing Way_ when they're surfing X while trying to write up their research.
2. **First Contact** - They read the chapter that's relevant to their research and then continue working on their dissertation.
3. **Participation** - Later, Noor returns to _The Turing Way_ and makes some suggestions and edits to that chapter.
4. **Sustained Participation** - They return to the repo periodically to read feedback on their commits and make additional comments, restricted to the one chapter they feel they know about.
@@ -88,7 +88,7 @@ They have lots of meetings throughout the workday, so are looking for ways to ma
They attend online webinars and watch videos on Youtube in their spare time to learn more about reproducibility and collaboration.
1. **Discovery** - Robin attended the [Women in Data Science webinar hosted by IBM Code Bristol](https://www.bigmarker.com/ibm-developer-uki/Women-in-Data-Science-IBM-Code-Bristol?bmid=2581093331c4), where they heard Malvika Sharan's talk *The Turing Way: A community built on a culture of collaboration*.
-2. **First Contact** - Robin was so inspired by the talk that they followed the [Turing Way on Twitter](https://twitter.com/turingway) and starred the [GitHub repository](https://github.com/the-turing-way/the-turing-way), to come back and learn more when they had time.
+2. **First Contact** - Robin was so inspired by the talk that they followed the [Turing Way on X](https://twitter.com/turingway) and starred the [GitHub repository](https://github.com/the-turing-way/the-turing-way), to come back and learn more when they had time.
3. **Participation** - When they find time at the weekend, Robin reads the chapter on Continuous Integration to pick up some tips and tricks - however they see that there isn't yet information on using GitHub Actions. Robyn would like to know more about this topic, so reads tutorials on how to incorporate them into their workflow and opens a [WIP] pull request to add a subsection to the chapter based on what they learn.
4. **Sustained Participation** - As their contributions are made outside of working hours, the process of learning, writing the subsection and iterating on feedback from _The Turing Way_ team moves at a [relatively] slower pace than someone who can contribute during working hours. Robin appreciates the assistance and communication from the team through the pull request conversation.
5. **Networked Participation** - Robin mentions _The Turing Way_ and what she learned about using GitHub Actions during one of her team's stand-ups, promoting their use to her colleagues.
From 529cae83bfc6d9093b9bffe2def8875a01871ab2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:08 +0000
Subject: [PATCH 103/142] Update source file persona-creation.md
---
book/website/project-design/persona/persona-creation.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/project-design/persona/persona-creation.md b/book/website/project-design/persona/persona-creation.md
index beccd30fdf6..f6279faaca8 100644
--- a/book/website/project-design/persona/persona-creation.md
+++ b/book/website/project-design/persona/persona-creation.md
@@ -77,7 +77,7 @@ You can sketch out this information by answering the following questions:
- What hobbies and interests your persona has?
- What personality/demeanor (such as introvert, extrovert) matches your persona's?
- Through which communication channel will your persona potentially find out about the event?
- - Some options: by email, mailing list or forums, Twitter, Facebook, Slack, Gitter, newsletters, website or community repository
+ - Some options: by email, mailing list or forums, X (formerly Twitter), Facebook, Slack, Gitter, newsletters, website or community repository
- What keeps your persona motivated on a typical day?
### Section 5: Provisions and opportunities
From e7b8a5f4a6113112eb9c0e905c10f9d0a662d500 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:31 +0000
Subject: [PATCH 104/142] Update source file ci.md
---
book/website/reproducible-research/ci.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/ci.md b/book/website/reproducible-research/ci.md
index c1c337769b2..545df6b981c 100644
--- a/book/website/reproducible-research/ci.md
+++ b/book/website/reproducible-research/ci.md
@@ -3,7 +3,7 @@
| Prerequisite | Importance | Notes |
| -------------|------------|-------|
-| [Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Necessary | Continuous integration will follow command line instructions
+| {ref}`Experience with the command line` | Necessary | Continuous integration will follow command line instructions
| {ref}`Version control` | Necessary | Continuous integration runs every time a new _commit_ is made to your project |
| {ref}`Reproducible computational environments` | Necessary | Continuous integration runs your tests on a separate computer (usually in the cloud) so you need to set it up in the same way. |
| {ref}`Testing` | Very helpful | Continuous integration _tests_ if anything important has changed when you make a change in your project |
From 7c0a67efceda800ad17e494d9d6758fb91ac8355 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:33 +0000
Subject: [PATCH 105/142] Update source file code-quality.md
---
book/website/reproducible-research/code-quality.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/code-quality.md b/book/website/reproducible-research/code-quality.md
index 27b603948c0..4266aa85588 100644
--- a/book/website/reproducible-research/code-quality.md
+++ b/book/website/reproducible-research/code-quality.md
@@ -3,7 +3,7 @@
| Prerequisite | Importance |
| --------------------------------------------------------------------------------------------- | ---------- |
-| [Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Helpful |
+| {ref}`Experience with the command line` | Helpful |
## Summary
From 6070fa4667f652cd94ed6e93bc301dff592f3fc5 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:34 +0000
Subject: [PATCH 106/142] Update source file code-quality-style.md
---
.../reproducible-research/code-quality/code-quality-style.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/code-quality/code-quality-style.md b/book/website/reproducible-research/code-quality/code-quality-style.md
index 5deed709dc5..b1ab161662d 100644
--- a/book/website/reproducible-research/code-quality/code-quality-style.md
+++ b/book/website/reproducible-research/code-quality/code-quality-style.md
@@ -69,4 +69,4 @@ Code quality analysis services are websites that often offer the following featu
- Optionally reports on code coverage generated by a CI build
- Automatically deploy the repository and generates a preview build for review before final release.
-For a list of choices see [shields.io](https://shields.io/category/analysis) or [this list of services that are free for open source projects](https://github.com/ripienaar/free-for-dev#code-quality).
+For a list of choices see [shields.io](https://shields.io/badges) or [this list of services that are free for open source projects](https://github.com/ripienaar/free-for-dev#code-quality).
From 8dd52c445dbe0f4f0ca3026b6a22d93057af1f7b Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:34 +0000
Subject: [PATCH 107/142] Update source file code-reuse-details.md
---
.../reproducible-research/code-reuse/code-reuse-details.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/code-reuse/code-reuse-details.md b/book/website/reproducible-research/code-reuse/code-reuse-details.md
index 01698d90e1c..7f49b616b77 100644
--- a/book/website/reproducible-research/code-reuse/code-reuse-details.md
+++ b/book/website/reproducible-research/code-reuse/code-reuse-details.md
@@ -44,7 +44,7 @@ Make sure you attach a license to your code and specify how you want to be cited
Consider using a permissive license that allows for reuse.
Also, you should choose a license which is compatible with the licenses of libraries or packages your software depends on.
-**See also**: {ref}`rr-licensing-software`, {ref}`rr-licensing-software-permissive`, {ref}`rr-licensing-compatibility`
+**See also**: {ref}`rr-licensing`, {ref}`rr-licensing-floss`, {ref}`rr-licensing-compatibility`
### 6. Make sure it is citable
From 49ef8c4178d076ed3a443080d79af1a7256ba26d Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:36 +0000
Subject: [PATCH 108/142] Update source file licensing.md
---
.../reproducible-research/licensing.md | 363 +++++++++++++++---
1 file changed, 304 insertions(+), 59 deletions(-)
diff --git a/book/website/reproducible-research/licensing.md b/book/website/reproducible-research/licensing.md
index 752f347e2e7..bece2744043 100644
--- a/book/website/reproducible-research/licensing.md
+++ b/book/website/reproducible-research/licensing.md
@@ -1,6 +1,15 @@
(rr-licensing)=
# Licensing
+```{figure} ../figures/licensing.*
+---
+height: 500px
+name: licensing
+alt: "A hand reaches out of an open safe and makes a thumbs up gesture. The Safe is high-tech tooking with circuit tracery on its surface. The thumb of the hand looks like a signed document. There is a happy face in green looking at the thumbs up from the open safe. In contrast on the other side of the image there is a locked version of a similar safe. There is a red and grumpy face looking at the locked safe which is being shaken in frustration."
+---
+Licensing. _The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
(rr-licensing-prerequisites)=
## Prerequisites
@@ -10,102 +19,338 @@ No previous knowledge is needed, this chapter explains how important it is to un
## Summary
> This chapter was written using American English, in which the word **license** is a noun **_and_** a verb.
-> With British English, however, **licence** is a noun (as in, _to issue a licence_), while **license** is a verb (as in, _they licensed the event_).
+> With British English, however, **license** is a noun (as in, _to issue a license_), while **license** is a verb (as in, _they licensed the event_).
+
+'Intellectual Property (IP)' law is a complex subject.
+However some understanding of it is important for anyone producing creative works governed by it including software, datasets, graphics and more.
+This is true irrespective of the nature of your project: Closed commercial projects building on open tooling; Commercial projects maintaining an open resource; Open community driven and/or non-profit projects.
+Each of these may need to make slightly different licensing choices from the beginning of their projects to be compatible with their goals.
+
+This chapter aims to give a brief summary of relevant intellectual property laws (enough to be able to read most software, and related licenses), explain free and open source software licensing, and explain how combining software from different sources works from a legal perspective.
+Decisions about licencing made at the inception of a project can have long-lasting and significant ramifications.
+The choices that you make about how your work is licensed shape who can and cannot legally use your work and for what purpose.
+Consequently, this chapter will feature some discussion of the ethical ramifications of licensing choices.
+It aims to be informative about the implications of licencing choices for the use of your work but not to prescribe a specific ethic, as there are divergent schools of thought on the ethics of different licencing choices.
+
+Many of the concepts which apply to the licensing of software, data, AI/ML models, hardware and other creative works such as visuals share common attributes and concepts which will be covered here.
+We will address the specifics of licensing each of these types of output in their own sub-chapters, as well as a separate sub-chapter on license compatability.
-As with anything else in society, some of what you can and cannot do in software (or hardware) development is determined by the law.
-Licensing is therefore an important aspect of sharing/publishing open source projects as it provides clarity for anyone looking to reuse an open source project.
-Without licenses in place, anyone who wants to reuse it will be left with legal ambiguity as to the status of using your intellectual property.
-Most of the constraints in this particular domain stem from intellectual property laws: laws that make abstract things like designs, stories, or computer programs resemble physical objects by allowing them to be owned.
-This chapter aims to give a brief summary of relevant intellectual property laws (enough to be able to read most software licenses), explain free and open source software licensing, and explain how combining software from different sources works from a legal perspective.
-It also gives some rules we have worked out to deal with common situations.
+Intellectual property is an umbrella term that refers to a number of distinct areas of law, primarily these three:
-## Motivation and Background
+- **[Copyright](https://europa.eu/youreurope/business/running-business/intellectual-property/copyright/index_en.htm#shortcut-1/)**
+- **[Patent](https://www.wipo.int/patents/en/)**
+- **[Trademark](https://euipo.europa.eu/ohimportal/en/trade-mark-definition/)**
-Without a license, all rights are with the author of the code, and that means nobody else can use, copy, distribute, or modify the work without consent.
-A license gives this consent.
-If you do not have a license for your research output, it is effectively unusable by the whole research community.
+What these have in common is the attempt to extend property rights to intangible goods, meaning their use by others can be prevented or [licensed](https://www.oshwa.org/faq/#what-is-a-license/).
+Governments with such laws effectively create a limited grant of monopoly over these goods for their creators, and other holders of these rights.
+This is generally done with the ostensible intent to incentivise the creation and improvement of such goods, but can in practice result in perverse incentives which fail to do so.
```{warning}
It is important to consider that copyright, licenses, and patents are all legal concepts.
As such, they are subject to what the law prescribes, which may change over time and space.
-This change is not only that one of the laws is changing over time, but it changes over space: depending on jurisdiction and enforcement.
Simply put, different countries have different laws, and follow different procedures with regard to enforcing them.
The content provided here is broadly based on American and European law and legal traditions.
It might not be applicable - might even be contra indicated - or relevant in your particular context.
-While things like the Berne Convention have sought to harmonize copyright enforcement, the real world is a messy place.
+However most nations are signatories to international treaty agreements which somewhat harmonise these laws notably the Berne Convention, the [TRIPS Agreement](https://www.wto.org/english/docs_e/legal_e/27-trips_01_e.htm), and others under the [World Intellectual Property Organization (WIPO)](https://www.wipo.int/portal/en/index.html).
+Whilst international efforts have sought to harmonize copyright enforcement, the real world is a messy place.
Good legal advice is timely, specific, and given by an expert; this chapter is none of these.
-It was written by an engineer, not by a lawyer, and it is a heavily simplified overview of a very complex field.
+It was written by engineers & scientists, not by lawyers, and it is a heavily simplified overview of a very complex field.
The intent is to give you an overview of the basics so that you will know when to check whether something you want to do has potential legal ramifications.
Do not make any important decisions based solely on the contents of this chapter.
So do not take the descriptions provided or viewpoints shared as legal advice, they are not that.
This document is not intended to be used in that manner.
-Consult a legal expert to provide actual legal advice for your case.
+Consult a legal expert to provide actual legal advice for your case.
+
```
-## Legal terms
+Perhaps the most relevant part of intellectual property law for software, data and other creative works is copyright.
+We will dispense quickly with patents and trademarks here, so we can move on to the main topic of copyright.
+
+(rr-licensing-patents)=
+## Patents
+
+The most important difference between patent and copyright to be immediately aware of is that by default all rights are retained by the author on works made public under copyright, whereas patents must be registered before their content is publicly disclosed.
+Thus, if you want to patent something, you must do so prior to sharing it publicly.
+The precise details of what constitutes a disclosure and the strictness of the application of this rule can vary by jurisdiction.
+
+Patents on processes and software rather than specific inventions are a matter of contention in US law and explicitly not recognised in EU law (at time of writing).
+Unlike copyright, you generally have to pay to register and maintain a patent.
+You must also do so in each jurisdiction in which you want this patent to apply, though some have reciprocal agreements for recognising patents from other jurisdictions.
+To ensure that patents held by the authors of software do not impact on the freedom to use and distribute open software, some licenses specifically include permission to use any applicable patents (for example section 3 of the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html)), though this cannot protect against patents held by 3rd parties.
+
+
+
+
+
+
+
+(rr-licensing-trademarks)=
+## Trademarks
+
+Trademarks are a brand, symbol, or identifying mark associated with a project, product or service.
+Trademarks differ from the copyright & patent in that their primary function is consumer protection.
+They prevent bad actors from impersonating recongnisable brands and deceiving consumers into purchasing products that are not being offered by who they think they are.
+They, like patents, must also be registered, but unlike patents, this can be done after they have been made public.
+
+Registering a trademark generally comes with an administrative fee, but is not as costly as maintaining a patent.
+Trademarks generally only apply within a specific sector, as people are unlikely to confuse brands which do completely different things.
+They can be relevant in the context of the name and logo of a software project, especially when a project changes hands or is forked, in which case the fork may not be able to use the original name of the project even if that project is no longer maintained.
+Open source projects not associated with a company which have trademarks may have these held by a legal entity such as a non-profit, through which they might also take donations and pay for project infrastructure.
+It can be valuable for open source projects to register for trademarks as their work can easily be cloned, modified and re-distributed with ill intent.
+Examples of modified open source tools distributed with malware added have been documented, and trademark enforcement could in some cases help to prevent or deter this.
+Nextcloud, for example, has a very [comprehensive guide to the use of their marks](https://nextcloud.com/trademarks/) with excellent explanations for the restrictions that they place on their use.
+
+
+
+
+
+(rr-licensing-copyright)=
+## Copyright
+
+
+
+By default, if you make a work publicly available, you retain the copyright to that work and all rights that this gives you over it.
+Anyone wishing to re-use that work must seek to license the right to do so from you, or open themselves to the possibility of a lawsuit for infringing on your copyright.
+Irrespective of how you choose to license your work, however, there are some generally accepted exceptions to the protections of copyright that permit the re-use of works (or parts of works) without the consent of the copyright holder, under certain circumstances.
+These are known as 'fair use' or 'fair dealing' exceptions.
+Under the 'fair use' standard originating in the USA, the following criteria are considered on a case-by-case basis to decide if a use constitutes an infringement of copyright:
+
+> From [17 U.S.C § 107](https://www.law.cornell.edu/uscode/text/17/107)
+> - the purpose and character of the use, including whether such use is of a commercial nature or is for nonprofit educational purposes;
+> - the nature of the copyrighted work;
+> - the amount and substantiality of the portion used in relation to the copyrighted work as a whole; and
+> - the effect of the use upon the potential market for or value of the copyrighted work.
+
+The 'fair dealing' standard, originating in British law, generally includes more explicitly enumerated exceptions but with similar intent.
+Notably disputes over what constitutes fair-use are not easily administrable and can require protracted court proceedings to settle definitively.
+
+
+For anyone wishing to circulate their work and grant others the right to re-use, remix, or re-distribute that work free of charge, coming to individual licensing arrangements with everyone who might want to do this is obviously impractical.
+To address this, there exist numerous pre-made 'off-the-self' licenses that you can apply to your work.
+Which of these you choose shapes how and under what circumstances others are permitted to re-use your work without infringing on your copyright.
-To understand what licenses do and how to apply them, it is first important to be familiar with a number of terms.
-Terms like copyright, licenses, patents, and trademarks are often used interchangeably (and sometimes incorrectly).
-This may lead to confusion as to what exactly is being discussed and what the implications are.
-Familiarise yourself with the following terms and follow the links to understand more about them.
+Pre-made licenses exist that are tailored to the differences between different types of works.
+For example, there are licenses intended to be used for software and licenses intended to be used for other creative works such as images, prose (text), as well as hardware & designs.
+In addition, there are now licenses tailored for machine learning or artificial intelligence models as these are comprised of several parts, including: training data, code, and model weights.
+Each of these parts may be licensed differently, and there is even some dispute as to whether model weights are subject to copyright at all under current law.
+
+This is an area which is likely to see (by legal standards) rapid changes in the near future, given recent developments in the commercialisation of AI/ML models.
-```{admonition} Info
-**[Copyright](https://europa.eu/youreurope/business/running-business/intellectual-property/copyright/index_en.htm#shortcut-1/):** “When you create an original literary, scientific and artistic work, such as poems, articles, films, songs or sculptures, you are protected by copyright.
-Nobody apart from you has the right to make the work public or reproduce it.
-” And, “If you create literary, scientific and artistic work, you automatically have copyright protection, which starts from the moment you create your work, so you don't need to go through any formal application process.”
+There are some general principles which apply to licenses across the different types of entity that they try to license.
+Licenses can generally be placed on a spectrum from proprietary, through permissive, to 'share alike' or 'copyleft' (the opposite of copyright).
+This spectrum is something of an oversimplification, and there are some extensions and caveats we'll get to later.
-**[License](https://www.oshwa.org/faq/#what-is-a-license/):** “Licensing is a way to give people rights that they wouldn’t otherwise have to use your intellectual property (IP) and, in return, to place restrictions on how they exercise those rights.”
-**[Patent](https://www.wipo.int/patents/en/):** “A patent is an exclusive right granted for an invention, which is a product or a process that provides, in general, a new way of doing something, or offers a new technical solution to a problem.
-To get a patent, technical information about the invention must be disclosed to the public in a patent application.”
-
-**[Trademark](https://euipo.europa.eu/ohimportal/en/trade-mark-definition/)**: "Trade marks are signs used in trade to identify products.
-Your trade mark is the symbol your customers use to pick you out.
-It distinguishes you from your competitors.
-You can protect and build upon your trade mark if you register it."
+(rr-licensing-floss)=
+## What is 'Free/Libre' or 'Open Source' software?
+These same concepts developed originally in the context of software have often been applied to other creative outputs.
+Consequently, they are among the most developed and useful context for understanding the licensing of other things.
+
+Software that is not free (in the 'libre' sense defined below) is proprietary.
+Software that you are not allowed to copy or modify falls into this category, as does software with usage restrictions, for example, "For research use only" or "For non-commercial use only".
+
+Permissively licensed things can generally be used by anyone for any purpose.
+A popular minimal example of this for software is known as the [MIT license](https://mit-license.org/), for other works, [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) the 'public domain' license.
+Copyleft licenses attempt to ensure that any re-distributions or derived works also remain 'free', the canonical example is the [GPL](https://www.gnu.org/licenses/gpl-3.0.html).
+Unlike permissively licensed content, which can be modified and redistributed under a different license (including as a part of a closed and/or for profit project), copyleft content (modified or unmodified) must be distributed under the same, or a compatible license, which retains the copyleft obligation.
+In other words if you take copyleft content, modify it, and distribute your modifications, those modifications must also be copyleft.
+
+The concept of copyleft licenses and their first example, the GPL, originated with Richard Stallman, who founded the free-software foundation (FSF) in 1985.
+The idea is a 'hack' of copyright law to use the protections that it affords to privately owned software to a software commons.
+
+
+The FSF's four fundamental freedoms of free/libre software are:
+
+- Freedom 0: The freedom to run the program as you wish, for any purpose.
+- Freedom 1: The freedom to study how the program works, and change it, so it does your computing as you wish.
+ Access to the source code is a precondition for this.
+- Freedom 2: The freedom to redistribute copies so you can help others in your community.
+- Freedom 3: The freedom to distribute copies of your modified versions to others.
+ By doing this, you can give the whole community a chance to benefit from your changes.
+ Access to the source code is a precondition for this.
+
+Other influential definitions of free and open source software include: The Debian project's [Debian Free Software Guidelines (DFSG)](https://www.debian.org/social_contract#guidelines), and the open source initiative (OSI)'s [Open Source Definition](https://opensource.org/osd/).
+The terms 'Free'/'Libre' & 'Open Source' software are often used somewhat interchangeably, but have different connotations.
+The use of 'free software' typically denotes a more hardline political commitment to the ideals of the free software movement, and is associated with a preference for copyleft licenses.
+The name 'open source' places the emphasis on freedom 1 and could more readily be confused with the concept of 'source available' software, based on a naive interpretation of the name.
+'Open source' is associated with, if not a preference for, then a more favourable view of, permissive licenses.
+
+```{note}
+The word 'free' in english does not distinguish something being monetarily free 'gratis' from politically free 'libre'.
+This is often summarised along the lines of: "free as in speech, not necessarily free as in beer"
+Thus the phrase 'libre software' is sometimes encountered in English to succinctly distinguish the concept of software which respects your liberty from software which is finacially free to use ('gratis').
+This ambiguity confusingly leads to the name 'Freeware' which is software that can be copied without paying anyone, but comes without source and cannot be modified.
+The 'free' in 'freeware' is gratis but not libre.
+It is also common to encounter the acronyms FOSS (Free and open source software) and FLOSS (Free/libre and open source software)
```
-Copyrights are generally what make open source licenses enforceable.
-For many open source licenses to be applicable, it is necessary to figure out what parts of the project are actually copyrightable and therefore can be licensed.
-
-## Copyleft Versus permissive
+The FSF contends that all software should respect these freedoms and that all software which does not respect these freedoms creates an asymmetric relationship between the users and developers of that software which can readily be abused by the developers to exploit their users.
+If developers are bad stewards of a free software projects, the friction for replacing them is lower, as all of the work put into the software does not need to be re-done.
+A 'fork' of the project can be made, developed and maintained by different developers whom the community of users deem a better steward.
+This is not true of proprietary projects where the developers own the rights to the code and thus cannot be readily replaced by the community of users if they begin to abuse these users who are now held captive by switching costs.
+It should be noted that an acrimonious project fork is quite uncommon and by no means always sucessful, it is the move of last resort.
+The credible threat of a fork redresses the power balance between developers and users giving users leverage if developers make unpopular choices.
+
+Copyleft licenses are an attempt to ensure that software remains effectively under community ownership and cannot be used to make proprietary software which does not respect the four freedoms and may thus result in the abuse of its users.
+To attempt to achieve this goal, copyleft software requires that when distributing copyleft software or in some cases derived works that you do so under the same terms as the original license.
+Creative commons 'share-alike' licenses attempt the same thing for other content.
+One of the advantages of this approach is that the simplest way to redistribute your changes is often to contribute them to the 'upstream project' or to 'upstream' them.
+If you add some features to a codebase for your own use and contribute them upstream then you get the advantage of the assistance of upstream maintainers in keeping your code up to date and working correctly with the rest of the project.
+You don't have to maintain your own fork and keep it up to date with the latest patches from the rest of the codebase and you don't have to manage your own distribution.
+All this also means that everyone else benefits from your improvements and you benefit from everyone elses'.
+Being a good open source citizen means playing by these rules and, if you can, contributing your fixes and improvements to upstream projects; not just freeloading off of them.
+
+Copyleft licenses do not prohibit commercial use, indeed numerous companies exist which develop copyleft projects.
+Many of those generate revenue through support services instead of selling licenses, which would incentivise an unhealthy relationship with their users.
+[Nextcloud](https://nextcloud.com/) is an excellent example of a commercial, open source project.
+Nextcloud makes use of the [AGPL v3.0](https://www.fsf.org/bulletin/2021/fall/the-fundamentals-of-the-agplv3) a license which extends the protections of the GPL to software used over a network.
+It gives users who interact with this software over a network, for example by using a web service, rather than run it on their own computers, the right to access a copy of the source code; which they are further free to modify and distribute as is usual for the GPL.
+
+Within copyleft licenses, there are 'strong' and 'weak' copyleft licenses.
+'Strong' copyleft licenses require that combined works which contain them as a library also carry the same license but weak copyleft licenses permit their re-distribution as a library within a combined work under a different license.
+We will define derived and combined works in the section on license compatibility where the detailed implications of the distinctions between strong & weak copyleft, and permissive licencing are explored in more practical detail.
+It is important to note that licenses can be incompatible such that creating a combined work is highly impractical to do legally.
+
+
+
+
+ | Free |
+ Proprietary |
+
+
+ | Copyleft |
+ Permissive |
+
+
+ | Strong |
+ Weak |
+
+
+
+
+ | GPL1 CDDL2 |
+ LGPL3 MPL4 |
+ BSD5 MIT6 Apache |
+ Research Only: No copying, No modification |
+
+
+
+
+ Licenses can either be Free or Proprietary, with Free Licenses further classified as Copyleft or Permissive.
+
+
+
+(rr-licensing-usage-restriction)=
+### What are 'Usage Restricting' Licenses?
+
+Usage restricting licenses seek to affirmatively protect users or others affected by the use of the work by placing specific restrictions on its use.
+This curtails freedom 0, the freedom to use software 'for any purpose' and prohibiting the use of the software, or other system, for unethical purposes.
+Both 'Ethical source' & 'Responsible AI' Licenses are examples of this approach and seek to place restrictions on the uses to which the licensees can put the software or machine learning systems licensed in this fashion.
+Consequently, these licenses by the classical definitions of free and open source software from the FSF and OSI would not be considered free or open source licenses. They do however generally resemble them in the other three criteria of the definition.
+Their merits versus conventional open source licenses have been the subject of some debate, and their adoption has thus far been relatively limited.
+
+Even an attribution requirement (the BY in CC-BY) can in some cases be considered a usage restriction.
+For example the Debian project found the [Common Public Attribution License (CPAL)](https://en.wikipedia.org/wiki/Common_Public_Attribution_License) to be incompatible their free-software guidelines for this reason whilst it is approved by the Open Source Initiative.
+In the case of academic works attribution requirements can serve to re-enforce the citation convention with the force of copyright law.
+
+(rr-licensing-choosing)=
+### Where to find open licenses for different types of work
+
+- Code
+ - The [Open Source Initiaitive (OSI)](https://opensource.org/licenses/) maintains a list of [approved licenses](https://opensource.org/licenses/) open source licenses
+ - [Free Software Foundation](https://www.fsf.org/) maintains a [list of GPL-Compatible Free Software Licenses](https://www.gnu.org/licenses/license-list.html#SoftwareLicenses)
+ - [GNU/FSF recomendations](https://www.gnu.org/licenses/license-recommendations.html)
+ - [choosealicense.com](https://choosealicense.com/) provides a tool to guide you through the license choice project.
+ - [Organisation for ethical source](https://ethicalsource.dev/) maintains a list of [ethical source licenses](https://ethicalsource.dev/licenses/)
+- Prose, Images, Audio, Video, Datasets, and similar
+ - [Creative Commons (CC)](https://creativecommons.org/)
+ - [Creative Commons License Chooser](https://creativecommons.org/choose/)
+ ```{figure} ../figures/cc-license-chart.*
+ ---
+ height: 500px
+ name: Creative Commons License Types
+ alt: >
+ Down the left hand side of the image there is a list of creative commons license types and their corresponding symbols, across the top is a list of properties of these licenses.
+ This creates a matrix to indicate which licenses have which properties using checkmarks.
+ Public Domain is represented by a C in a circle with a line through it.
+ CC 0 allows you to copy and publish, does not require attribution, allows commercial use, allows you to modify and adapt, and allows you to change the license.
+ By attribution is represented by a person in a circle.
+ CC BY allows you to copy and publish, requires attribution, allows commercial use, allows you to modify and adapt, and allows you to change the license.
+ By attribution share alike is represented by a person in a circle and a circular arrow in a circle.
+ CC BY SA allows you to copy and publish, requires attribution, allows commercial use, allows you to modify and adapt, but does not allow you to change the license.
+ By attribution no derivatives is represented by a person in a circle and an equals sign in a circle
+ CC BY ND allows you to copy and publish, requires attribution, allows commercial use, does not allow you to modify and adapt, and allows you to change the license.
+ By attribution non commercial is represented by a person in a circle and a dollar sign in a circle with a line through it
+ CC BY NC allows you to copy and publish, requires attribution, does not allow commercial use, allows you to modify and adapt, and allows you to change the license.
+ By attribution non commercial share alike is represented by a person in a circle, a dollar sign in a circle with a line through it, and a circular arrow in a circle.
+ CC BY NC SA allows you to copy and publish, requires attribution, does not allow commercial use, allows you to modify and adapt, and does not allow you to change the license.
+ By attribution non commercial no derivatives is represented by a person in a circle, a dollar sign in a circle with a line through it, and an equals sign in a circle.
+ CC BY NC ND allows you to copy and publish, requires attribution, does not allow commercial use, does not allow you to modify and adapt, and allows you to change the license.
+ ---
+ Creative Commons License Types. From [George Washington University Libraries Open Textbooks](https://libguides.gwu.edu/opentextbooks/creative_commons). Used under a CC-BY 4.0 licence.
+ ```
+- Machine Learning (ML) / artificial inteligence (AI) systems
+ - Creative commons and Software licenses can be applied to different parts of ML/AI systems, CC to training data and weights, software licenses to code used in training / depoyment.
+ - [Responsible AI Licenses (RAIL)](https://www.licenses.ai/)
+
+(rr-licensing-enforcement)=
+### Licencing enforcement
+
+There have been a number of successful legal cases that have been brought in defence of the terms of copyleft licenses obliging the parties abusing the terms of these licenses to appropriately release their code.
+But this can be hard to discover, as it is not immediately obvious if copyleft code has been used from looking at a black box proprietary end product.
+
+
+
+Organisations which take legal action in defence of free software, and which can provide information and resources for anyone else seeking to do the same, include:
-In broad terms copyleft licenses impose an obligation of reciprocity on users of any of the licensed items.
-If something is licensed under a copyleft license, then any derivative works need to be shared under the same rights.
-Note that it can make things difficult if you want to combine different elements having different copy-left licenses.
-Most copyleft licenses fall under open source licenses but not all open source licenses are copyleft.
+- [Software Freedom concervancy](https://sfconservancy.org/)
+- [Software Freedom Law Centre](https://softwarefreedom.org/)
+- [FSF - licensing and compliance](https://www.fsf.org/licensing/)
+- [Free Software Foundation Europe (FSFe) - legal work](https://fsfe.org/activities/legal.en.html)
+- [Electronic Fontiers Foundation - legal cases](https://www.eff.org/cases)
-Copyleft licenses do not prohibit the commercial use of the copyrighted content.
-It only prohibit you to place additional restrictions on the derivative work.
+(rr-licensing-edge)=
+### Pertinant edge cases
-Permissive licenses are those licenses that do not impose the reciprocity requirements.
-These licenses allow for the proprietary licensing of derivative works.
+(rr-licensing-edge-clas)=
+#### Contributor license Agreements
-A more detailed explanation is given in the chapter on license for software. {ref}`rr-licensing-software-permissive`.
+The holder of the copyright on a copyleft project can still re-license that project or dual-license that project under a different license, for example to grant exclusive rights to commercially distribute that project with proprietary extensions or to make future versions proprietary.
+In a large community developed project, this would require the consent of all contributors, as they each own the copyright to their contributions.
+To get around this, some copyleft projects developed by companies that commercially license proprietary extensions to these projects ask their contributors to sign contributor license agreements (CLAs) which may assign the contributor's copyright to the company, or include other provisions so that they can legally dual-license the project.
+(rr-licensing-edge-available)=
+#### 'Source Available' or 'Shared Source'
-### How and where to add licenses
-The choice of license is a personal one based on the goals of the project and the scope for collaboration and growth.
-However, structuring the project and adding the appropriate licenses to the different section is much more universal.
+Under a proprietary license the code is generally not made public.
+Some projects share their code but do not license its re-use, modification or redistribution.
+This is known as being 'source available' or 'shared-source', the [Vivaldi](https://vivaldi.com/) web browser is an example of such a project.
-The licenses used should generally be featured in the main page where the project is hosted.
-For example if GitHub is used, a license file should be added to the topmost layer of the repo along with a Readme file.
-The appropriate licenses should also attached to the different elements.
-For example the software license should be attached to the code, with the appropriate declaration at the start of any section.
+(rr-licensing-welcoming)=
+## Being a welcoming space to those who do not want to use proprietary software
-### Limitations
-It is important to keep in mind that licenses are only as powerful as the ability to enforce them.
-This means that while you can curate and choose the best license that fits your goals, it might entirely be redundant if enforcement is not possible.
+Some people avoid using non-free software on principle to the greatest extent that they can.
+It is highly impractical to completely avoid all non-free software in the world today, so many have compromises and workarounds.
+This might include measures such as only running proprietary code in a sandboxed environment like a web browser, but this can impose an additional burden on these users.
+This is especially true if proprietary tools do not offer first class features in browsers or support free software operating systems like Linux.
+Consequently, the choice to use open infrastructure is important if you want to be inclusive of people who adhere strongly to the free software ethos and consider being asked to use non-free software as an imposition.
+A small minority of people simply will not participate if doing so requires that they use non-free software.
-The good news is that open source software licenses have been tested across different jurisdictions and have been upheld in many cases, including the USA and Germany.
-The full scope of enforceability and effectiveness is still to be explored.
-## Extra notes
+(rr-licensing-where)=
+## How and where to add licenses
-It is highly recommended to provide an [SPDX short license identifier](https://spdx.org/licenses/) to make the licensing terms machine-referenceable.
\ No newline at end of file
+Wherever you share your project it is likely to be organised in a heirarchy of directories, place a plain text file containing the license in the top level directoty of your project.
+If it is a git project for example that is shared on a git forge like github or gitlab, using a standard file name like `LICENSE` will allow your license to be picked up the the host and displayed on your project.
+If the license that you have used has a standarised short name from [SPDX](https://spdx.org/licenses/) then this will be displayed as a small icon on your projects home page by these hosts.
+It can also be useful to include license information in the form of standard strings at the top of each text file in your project.
+There are useful tools which automate this available from [REUSE](https://reuse.software/) a project from the [FSFe](https://fsfe.org/) which developed the spec.
+This is especially true if your project contains material that is licensed in multiple different ways or a part of your project is being used in someone else's which uses a different (compatible) license.
From eefd51e84560aa57b714cbb8a015491311f7b022 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:36 +0000
Subject: [PATCH 109/142] Update source file licensing-checklist.md
---
.../licensing/licensing-checklist.md | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/book/website/reproducible-research/licensing/licensing-checklist.md b/book/website/reproducible-research/licensing/licensing-checklist.md
index 5ec2b229fc9..5037fd57545 100644
--- a/book/website/reproducible-research/licensing/licensing-checklist.md
+++ b/book/website/reproducible-research/licensing/licensing-checklist.md
@@ -15,3 +15,21 @@ This is a checklist for adding a license to your project repository.
Additional resources you can read to learn more about software licenses.
- [Open source licenses: What, which, and why](https://arstechnica.com/gadgets/2020/02/how-to-choose-an-open-source-license/)
+
+- General Reading on copyright, its potential reforms, and history of application in software
+ - [Free as in freedom 2.0](https://archive.org/details/faif-2.0/mode/2up)
+ - [What if we could reimagine copyright?](https://www.jstor.org/stable/j.ctt1q1crjg)
+ - [Chokepoint capitalism](https://craphound.com/chokepoint/2022/09/27/twitch-does-a-chokepoint-capitalism/)
+ - [Intellectual Property & Monopoly Capitalism]( https://crashcourseeconomics.org/webinar/intellectual-property-and-monopoly-capitalism)
+ - [Can models be protected by copyright law?](https://www.comsol.com/blogs/can-models-be-protected-by-copyright-law/)
+- Tools
+ - [Reuse](https://reuse.software/)
+- Relevant Legal Materials
+ - International treaties impacting most nation state level IP law
+ - [Berne Convention for the Protection of Literary and Artistic Works](https://www.wipo.int/treaties/en/ip/berne/)
+ - [TRIPS](https://www.wto.org/english/docs_e/legal_e/27-trips_01_e.htm)
+ - Statutes / Directives
+ - US
+ - [DMCA](https://www.congress.gov/bill/105th-congress/house-bill/2281)
+
+
From 152ad644456a2708e87dcdc513e70b31f59d4690 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:37 +0000
Subject: [PATCH 110/142] Update source file licensing-compatibility.md
---
.../licensing/licensing-compatibility.md | 96 ++++++++++++++++++-
1 file changed, 95 insertions(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/licensing/licensing-compatibility.md b/book/website/reproducible-research/licensing/licensing-compatibility.md
index abaa74b07cf..2023645ffe9 100644
--- a/book/website/reproducible-research/licensing/licensing-compatibility.md
+++ b/book/website/reproducible-research/licensing/licensing-compatibility.md
@@ -6,8 +6,101 @@ If these constraints conflict, then you cannot legally distribute the result (if
If two licenses specify incompatible constraints on the license of the combined work, then they are _incompatible_.
+(rr-licensing-software-derivative)=
+## Derivative Software
+
+Within the category of free software, there are several subcategories, which are distinguished by what is allowed when making derivative software.
+There are two basic ways of making a derivative work of a program or library: modifying it (forking), or combining it with other software (for example using a library in your program).
+Of course, you can modify and then combine as well.
+
+Modifying a program leads to a new program that is derived from the original.
+This is similar to deriving the new edition of a textbook from the original.
+Both the original and modified versions are works under copyright law, and both of them may be licensed.
+
+As an example of combining software, imagine a program A that uses two preexisting libraries B and C.
+The complete program A will consist of library B, library C, and some code D that connects the libraries together and perhaps adds additional functionality.
+Each of these four items is a work of authorship with a license.
+Program A can sometimes be referred to as the "Combined work", "Work as a whole" or "Larger work".
+
+Different free software licenses place different constraints on how modified versions and combined works can be licensed.
+
+Copyleft licenses add some restrictions to the licensing of derivative works.
+Like permissive licenses, they let you distribute the software unchanged under that license.
+However, if you distribute a binary, then you have to include the source code as well.
+Modified versions have to be distributed under the same license as the original; you are not allowed to change the license.
+
The GNU GPL, for instance, is incompatible with proprietary licenses, because it requires the combined work to be licensed under the GPL, with no additional restrictions allowed.
-Having a part of the work under a proprietary license is such an additional restriction, so you cannot distribute such a combination (unless the copyright owner of the GPL code gives special permission).
+Having a part of the work under a proprietary license is such an additional restriction, so you cannot distribute such a combination, unless the copyright owner of the GPL code gives special permission.
+However, GPL codebases often have many contributors and you need all of their permission. This is an intended feature of the license which is by design hostile to being re-licensed in a proprietary fashion.
+{ref}`Contributor License Agreements (CLAs)` can be used by GPL projects circumvent this by empowering a single party to make decisions about relicensing if they want to allow for dual licensing of GPL or AGPL codebases.
+
+When creating a combined work, a further distinction can be made.
+_Strong_ copyleft licenses on a component require a combined work to be licensed under the same license as the component.
+In the example above, if library B is distributed under a strong copyleft license such as the GNU GPL, then program A must be distributed under that same license.
+
+_Weak_ copyleft licenses allow the combined work (A) to be distributed under any license, as long as the source for the licensed component (B) is also made available under its original license.
+They may also require that the recipient of the combined work can re-link the modules after modifying the component.
+
+(rr-licensing-software-overview)=
+## Permission Overview
+
+
+
+
+ |
+ Copyleft |
+ Permissive |
+ Proprietary |
+
+
+ | Strong |
+ Weak |
+
+
+
+
+ | Use for anything |
+ Yes |
+ Yes |
+ Yes |
+ Sometimes |
+
+
+ | Private changes |
+ Yes |
+ Yes |
+ Yes |
+ Rarely |
+
+
+ | Distribute original |
+ Same license, with source |
+ Same license, with source |
+ Same license, also binary-only1 |
+ Rarely |
+
+
+ | Distribute modified |
+ Same license, with source |
+ Same license, with source2 |
+ Any license, also binary-only |
+ Rarely |
+
+
+ | Distribute combined |
+ Same license, with source |
+ Any license, binary additions |
+ Any license, also binary-only |
+ Rarely |
+
+
+
+
+ Permissive licenses grant the largest set of permissions to users. Copyleft licenses require redistribution of the original or modified source to use the same license, with weak copyleft licences allowing a different choice of license for the combined work. Proprietary licenses rarely provide any permissions beyond the right to use the software.
+
+
When you use different pieces of software together to solve a problem, and want to distribute the result, here are the questions you have to answer:
@@ -248,6 +341,7 @@ If it did not include OpenIFS, it would have to be distributed under the GPLv3,
#### Can we work on this privately, without distributing anything?
The GPL allows making private modifications of software covered by it, with no restrictions, provided the changed software is not distributed at all.
+In the case of the AGPL, running a server interacted with in some way by users over a network is equivalent to distribution under the GPL and you would be required to provide any users with the source code.
The OpenIFS license also allows making private modifications.
So we can work on this project (and prepare and run combined works) without violating the licenses, as long as we do not share the results with anyone.
From 9dc8ac45a21f6d5e331fda475672e317696cfa9a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:38 +0000
Subject: [PATCH 111/142] Update source file licensing-ethical-source.md
---
.../licensing/licensing-ethical-source.md | 76 +++++++++++++++++++
1 file changed, 76 insertions(+)
create mode 100644 book/website/reproducible-research/licensing/licensing-ethical-source.md
diff --git a/book/website/reproducible-research/licensing/licensing-ethical-source.md b/book/website/reproducible-research/licensing/licensing-ethical-source.md
new file mode 100644
index 00000000000..8d16e7879f1
--- /dev/null
+++ b/book/website/reproducible-research/licensing/licensing-ethical-source.md
@@ -0,0 +1,76 @@
+(rr-licensing-ethical)=
+# 'Ethical Source'
+
+The ethical source movement seeks to affirmatively protect specific user rights by curtailing freedom 0, the freedom to use software 'for any purpose' and prohibiting the use of the software for unethical purposes.
+Consequently, these licenses by the classical definitions of free and open source software from the FSF and OSI would not be considered free or open source licenses.
+Ethical Source licenses do generally resemble conventional free/libre and open source in the other three criteria of the definition.
+Their merits versus conventional open source licenses has been the subject of some debate, and their adoption has thus far been relatively limited.
+
+A leading figure in this movement is Coraline Ada Ehmke creator of the [Contributor Covenant](https://www.contributor-covenant.org/), the [Hippocratic License](https://firstdonoharm.dev/), and the founder in 2020 of the [Organisation for Ethical Source](https://ethicalsource.dev/).
+In the words of its advocates, [Ethical Source](https://ethicalsource.dev/) was created to "empower developers, giving us the freedom and agency to ensure that our work is being used for social good and in service of human rights."
+Motivated by the growing use of open source software for technologies such as mass surveillance and racial profiling, the movement aims to reduce this "misuse" of open source software.
+
+Ethical Source extends upon the principles of open source to provide developers additional means to ensure their work is used for applications aligned with ethical values important to them like:
+
+- Advocating for workers' rights and human rights
+- Ensuring protections against violence and discrimination
+- Protecting privacy
+
+A list of Ethical Licenses and their targeted applications can be found on the [Ethical Source website](https://ethicalsource.dev/licenses/).
+The core Hippocratic license, for example, prohibits a variety of human rights abuses and mandates equal pay for equal work.
+It can be further extended using [their license building tool](https://firstdonoharm.dev/build/) with modules covering:
+
+- Fossil Fuel Divestment
+- Ecocide
+- Extractive Industries
+- Boycott / Divestment / Sanctions
+- Taliban
+- Myanmar
+- Xinjiang Uygur Autonomous Region
+- US Tariff Act
+- Mass Surveillance
+- Military Activities
+- Law Enforcement
+- Media
+- Social Auditing
+- Workers on Board of Directors
+- Supply Chain Transparency
+- Copyleft
+
+Licensees are given 30 days upon notification of a violation or harm to remedy them before the license is terminated.
+The potential difficulty of demonstrating compliance with these terms and of bringing effective legal action against any party not complying with them has attracted some skepticism about the effectiveness of this approach.
+
+Whilst many potential violaters of these license terms lie outside the jurisdictional reach of courts which might enforce them, many also do business with partners which might reside within the reach of these courts.
+If for example Thermo Fisher Scientific had been using a library licensed under the Hippocratic license, especially one using the Xinjiang Uygur Autonomous Region module, in the software on their sequencing instruments they might have opened themselves up to liability when [selling DNA testing equipment to police departements in Xinjiang and Tibet](https://theintercept.com/2022/09/13/china-tibet-police-dna-thermo-fisher/) legal action against them in the US courts is more plausible than legal action against the CCP.
+The challenge might then be one of persuading such companies to expose themselves to the liabilities associated with using software with these licenses.
+
+(rr-licensing-ethical-risks)=
+## Potential Risks
+
+In the absence of case law deciding on license enforcement decisions for these licenses it is as yet unknown what (if any) administrative burden may be associated with demonstrating compliance with ethical source and RAIL licenses.
+Whilst unlikely for any given user of software licensed in this fashion, it is hypothetically possible that such licenses could be weaponised by bad actors seeking to impose costs on the entities using the licenses, as [has occurred before](https://onezero.medium.com/beware-the-copyleft-trolls-a8b85c66b7eb) with 'exploits' in open licenses.
+A well-intentioned organisation using tools under such a license could theoretically be sued for not complying with the terms of these licenses and have to pay legal fees and/or incur other expenses associated with demonstrating compliance with the terms, depending on decisions made during the legal process.
+These licenses, because they impose greater restrictions on their licensees, expose a greater attack surface for such bad actors.
+Compliance with the terms of conventional free software licenses is relatively easy to demonstrate.
+To comply you can simply share the code, if you have a well managed internal code repositories this should be inexpensive.
+(If you have to comb through your git history to remove secrets you inadvisedly committed then things might get more expensive.)
+Compliance with the terms of an ethical source license may however be considerably more complex and expensive to demonstrate definitively.
+Such cost are less likely to be weaponised against indiviual end users of software licensed in this fashion but rather institutions which depend on software on this kind.
+Institutions which are either small enough have their finances serioulsy damaged or their operation immpeeded, or which are large enough to extract a monetary settlement of some kind, would be possible targets.
+In short they suffer from the same issues as fair-use exemptions, they are not readily administrable.
+
+Even if it is not the intent of proponents of ethical source some parties may seek to use technical enforcement measures, also known as digital rights/restrictions management (DRM), to enforce the terms of ethical source licenses.
+Returning to the earlier example, if sequencing instruments being used for unlicensed purposes could be remotely disabled by their manufactures this raises some questions.
+What about the use of these machines with 3rd party or unlicensed components in places which cannot afford 'official' components but which need to use these machines for public health reasons?
+Property rights, the 'doctrine of first sale', and 'right(s) to repair' would conventionally protect the osstensible owners of equipment from such an imposition by its original manufacturer.
+These rights come at the expense of being able to use technical enforcement measures to police the misuse of these systems but with the bennefit of protecting the freedoms to do as you will with your own property.
+Technical enforcement measures are often brittle, what happens when your sequencer can't phone home to check-in with the server that tells it if its license is valid, or when that server disappears because the model is no longer in its official support window?
+Technical enforcement measures are often invasive, to avoid being circumvented they must run with the highest level of priviledge on a system and this access can readily be abused to surveil users as well as creating a security weakness.
+Technical enforcement measures are often ineffective, they can often be bypassed by technically compentant users who can share their bypasses with other less technical users.
+These measures are often more effective legally than they are technically due to the existence of 'anti-circumvention' laws.
+The canonical example of an anti-circumvention law is [17 U.S. Code § 1201](https://www.law.cornell.edu/uscode/text/17/1201) but many other jurisdictions have equivalent statutes as a results of treaty and trade agreements.
+These laws criminalise bypassing such protections meaning that law abiding users must suffer the downsides of technical enforcement whilst the supposed targets, often outside the jurisdiction of would be enforcers, simply circumvent these measures and use them anyway.
+This often permits manufactures to abuse these statues to prevent users of their products from using them in ways not in the financial interest of the original manufacturer such as by using cheaper 3rd party consumables or repairs.
+Manufactuers can also leverage their ongoing access to their devices to non-consensually, (generally with the veneer of consent provided by requiring the acceptance of an end user license agreement (EULA)), spy on end users harvesting their data and extracting value from it.
+Expanded usage restrictions could create an incentive or excuse for manufactures to strengthen or expand technical enforcement measures.
+It could be argued that they now have a greater obligation to police the use of their tools in order to demonstate compliance with these licenses.
From 0c7f38bb455e73dd9ccb5fa8c33daf39b06e577c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:38 +0000
Subject: [PATCH 112/142] Update source file licensing-hardware.md
---
.../reproducible-research/licensing/licensing-hardware.md | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/book/website/reproducible-research/licensing/licensing-hardware.md b/book/website/reproducible-research/licensing/licensing-hardware.md
index 5715df8f648..bbdc247b35d 100644
--- a/book/website/reproducible-research/licensing/licensing-hardware.md
+++ b/book/website/reproducible-research/licensing/licensing-hardware.md
@@ -4,8 +4,7 @@
(rr-licensing-hardware-prerequisites)=
## Prerequisites
-This chapter builds on the chapter {ref}`rr-licensing`.
-It is advisable to also read the chapter {ref}`rr-licensing-software` before or after reading this one.
+This chapter builds on the chapter {ref}`rr-licensing` and it is advisable to read it before reading this one.
## Introduction
@@ -73,7 +72,7 @@ Depending on the type of project and scope one or two elements might not be rele
#### Hardware design and licenses
This consists of the actual hardware elements of the project and utilising a license like a CERN OHL would be appropriate.
-This element consists of the functional parts of the “product”.
+This element consists of the functional parts of the "product".
In general, functional parts of an invention could be protected by a patent, but in our context the Open Hardware Licenses play that role.
Since a patent has to be specifically applied for and given by the patent office of the country, the aspects that the open hardware licence actually protects can be uncertain.
From d3e3fdeaed37a65c949e8de73d62bd11a8f85a79 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:39 +0000
Subject: [PATCH 113/142] Update source file licensing-ml.md
---
.../licensing/licensing-ml.md | 87 ++++++++++++++++++-
1 file changed, 84 insertions(+), 3 deletions(-)
diff --git a/book/website/reproducible-research/licensing/licensing-ml.md b/book/website/reproducible-research/licensing/licensing-ml.md
index c3267ec8477..77547129282 100644
--- a/book/website/reproducible-research/licensing/licensing-ml.md
+++ b/book/website/reproducible-research/licensing/licensing-ml.md
@@ -1,10 +1,31 @@
(rr-licensing-ml)=
-# Machine Learning Model Licenses
+# Licensing Machine Learning models
+
+## Legal Status of AI/ML model weights
+
+It is an open question wether {term}`AI`/{term}`ML` models weights are even copyrightable.
+US copyright law specifically excludes the following from works eligible for copyright protection: "any idea, procedure, process, system, method of operation, concept, principle, or discovery, regardless of the form in which it is described, explained, illustrated, or embodied in such work."
+In addition the US Copyright Office has stated that this exclusion extends to "scientific or technical methods or discoveries;" "mathematical principles;" and "formulas or algorithms."
+
+A legal doctrine known as the [idea–expression distinction/dichotomy](https://en.wikipedia.org/wiki/Idea%E2%80%93expression_distinction) draws a distinction between an abstract idea and a specific implementation, where code authored by a human that implements an algorithm is copyrightable as a creative work of authorship but the algorithm itself is not.
+
+It is also generally accepted in US copyright law that to be copyrightable a work must be a product of human creative authorship and not that of an automated process.
+
+It is not obvious if model weights would be considered works of human authorship or rather the results of automated processes, as a general principle or discovery or as a specific implementation.
+These questions will need to be decided on by the courts and/or legislated on before the status of model weights can be properly established.
+
+In the absence of clarity on this point many organisations are taking the calculated risk of operating under the assumption that they are copyrightable and generally treating them similarly to datasets and/or software.
+Some companies are offering legal protections for users of services based on these systems, offering to cover legal expenses arising from challenges to the copyright status of the outputs of these systems.
+It is possible that some form of copyright-like protection will be explicitly extended to model weights but it's precise contours are yet to be determined.
+
+Despite these open questions AI/ML model specific licenses are already being developed.
+
+## Machine Learning Model Licenses
Like a software license, a Machine Learning (ML) model license governs the use, redistribution of the model and/or algorithm, and distribution of any derivatives of it.
However, there are other components to an AI system, such as {ref}`data`,
-{ref}`source code`, or applications, which may have their own separate licenses.
-ML model licenses may restrict the use of the model for specific scenarios for which, due to the technical capabilities and limitations of the model informed by its model card, the licensor is not comfortable that the model is used.
+{ref}`source code`, or applications, which may have their own separate licenses.
+ML model licenses may restrict the use of the model for specific scenarios for which, due to the technical capabilities and limitations of the model informed by its model card, the licensor is not comfortable that the model is used.
While many ML models may utilise open software licensing (for example MIT, Apache 2.0),
there are a number of ML model-specific licenses that may be developed for a specific model (for example [OPT-175B license](https://github.com/facebookresearch/metaseq/blob/main/projects/OPT/MODEL_LICENSE.md), [BigScience BLOOM RAIL v1.0 License](https://https://bigscience.huggingface.co/blog/the-bigscience-rail-license)),
@@ -48,6 +69,66 @@ alt: An illustration depicting a flow chart diagram for a decision making proces
The OpenRAIL flow chart aids the selection and naming of a license for an ML project. Danish Contractor, Carlos Muñoz Ferrandis, Jenny Lee, & Daniel Mcduff. (2022, August).
```
+(rr-licensing-ethics-copyright-responsible-rail)=
+### OpenRAIL License types
+
+These same principles developed in {ref}`'ethical source'` apply to the 'Open' variants of the licences from RAIL (Responsible AI Licences).
+In that, they are attempting to place restrictions on the uses to which licensees can put the thing being licenced.
+Traditional software has many of the same concerns which affect machine learning models, and indeed also often contain assets such as images which may be licenced differently from software with which they are bundled.
+The primary differences being governance of data used in training the models (see: {ref}`Data Governance for the Machine Learning Pipeline`) and the lack of interpretability of the decisions of many ML systems, though this latter point can also be an issue for conventional systems if they are closed.
+RAIL provides a succinct way of expressing licences for combined machine learning systems which include, the data on which they were trained, the software used to specify this, the model weights generated as a result and the applications which provide an interface to the resulting model.
+
+RAIL provides these definitions of the modifiers that can be applied to their licenses:
+
+> - **D**ata: The dataset(s) used to pretrain or train an AI Model.
+> - **A**pplication/service: Any executable software code or application, including API-based remote access to software.
+> - **M**odel: Machine-learning based assemblies (including checkpoints), consisting of learnt weights and parameters (including optimizer states), corresponding to the model architecture.
+> - **S**ource: The source code and scripts associated with the AI system.
+
+Therefore:
+
+> - RAIL-D: RAIL License includes Use Restrictions only applied to the data
+> - RAIL-A: RAIL License includes Use Restrictions only applied to the application/executable
+> - RAIL-M: RAIL License includes Use Restrictions only applied to the model
+> - RAIL-S: RAIL License includes Use Restrictions only applied to the source code
+
+These are the restrictions placed on the licencee of a RAIL-M license:
+
+> You agree not to use the Model or Derivatives of the Model:
+>
+> **a.** In any way that violates any applicable national, federal, state, local or international law or regulation;
+>
+> **b.** For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+>
+> **c.** To generate or disseminate verifiably false information and/or content with the purpose of harming others;
+>
+> **d.** To generate or disseminate personal identifiable information that can be used to harm an individual;
+>
+> **e.** To generate or disseminate information and/or content (for example images, code, posts, articles), and place the information and/or content in any context (for example bot generating tweets) without expressly and intelligibly disclaiming that the information and/or content is machine generated;
+>
+> **f.** To defame, disparage or otherwise harass others;
+>
+> **g.** To impersonate or attempt to impersonate (for example deepfakes) others without their consent;
+>
+> **h.** For fully automated decision making that adversely impacts an individual’s legal rights or otherwise creates or modifies a binding, enforceable obligation;
+>
+> **i.** For any use intended to or which has the effect of discriminating against or harming individuals or groups based on online or offline social behavior or known or predicted personal or personality characteristics;
+>
+> **j.** To exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+>
+> **k.** For any use intended to or which has the effect of discriminating against individuals or groups based on legally protected characteristics or categories;
+>
+> **l.** To provide medical advice and medical results interpretation;
+>
+> **m.** To generate or disseminate information for the purpose to be used for administration of justice, law enforcement, immigration or asylum processes, such as predicting an individual will commit fraud/crime commitment (for example by text profiling, drawing causal relationships between assertions made in documents, indiscriminate and arbitrarily-targeted use).
+
+RAIL-S licences carry their [Software Usage Restrictions](https://www.licenses.ai/source-code-license).
+
+RAIL license can be used in closed applications and Open RAIL licenses are permissive with respect to the model and software but not with respect to the usage restrictions.
+Note that there is not an effective equivalent to a copyleft version of the Open RAIL licences.
+None of them require that the software or models contained in them also be similarly licenced in derived works, only that the usage restrictions be retained.
+This could be a useful extension to these license adding an 'L' for copy**L**eft and including a clause making any software, model weights, or source code in the bundle strong copyleft.
+
### Example: OpenRAIL-M
The 2 main features of an OpenRAIL license are:
From a1727fb7b509b02c002a999af9640bbbbab6fbf2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:39 +0000
Subject: [PATCH 114/142] Update source file make.md
---
book/website/reproducible-research/make.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/make.md b/book/website/reproducible-research/make.md
index 5a6ec4c34de..a6e7c93d127 100644
--- a/book/website/reproducible-research/make.md
+++ b/book/website/reproducible-research/make.md
@@ -6,7 +6,7 @@
| Prerequisite | Importance | Notes |
| ------------ | ---------- | ----- |
-| [Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Necessary | |
+| {ref}`Experience with the command line` | Necessary | |
| {ref}`Version Control` | Helpful | Experience using git is useful to follow along with examples |
Recommended skill level: intermediate
From e09eea48763a9c739a15a021ee6a84358cf4d0ee Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:41 +0000
Subject: [PATCH 115/142] Update source file open.md
---
book/website/reproducible-research/open.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/open.md b/book/website/reproducible-research/open.md
index 60ef321016d..dd6b16562a4 100644
--- a/book/website/reproducible-research/open.md
+++ b/book/website/reproducible-research/open.md
@@ -66,7 +66,7 @@ height: 500px
name: open-access-citations
alt: A plot of the relative citation rate (OA divided by non-OA), in the x axis, for 19 different areas of knowledge, in the y axis. The areas of knowledge are organized from the highest to the lowest Relative Citation Rate in the following order - Agricultural Studies, Physics/Astronomy, Medicine, Computer Science, Sociology/Social Sciences, Psychology, Political Science, Management, Law, Economics, Mathematics, Health, Engineering, Philosophy, Education, Business, Communications Studies, Ecology, and Biology. The highest mean values are around 3.2 for Agricultural Studies, and the lowest are around 1.2 for Biology.
---
-The relative citation rate (OA: non-OA) in 19 fields of research. This rate is defined as the mean citation rate of OA articles divided by the mean citation rate of non-OA articles. Multiple points for the same discipline indicate different estimates from the same study or estimates from several studies. (See footnote 1 for references.)
+The relative citation rate (OA: non-OA) in 19 fields of research. This rate is defined as the mean citation rate of OA articles divided by the mean citation rate of non-OA articles. Multiple points for the same discipline indicate different estimates from the same study or estimates from several studies. (See {cite:ps}`McKiernan2016Open`.)
```
Another benefit of openness is that while research collaborations are essential to advancing knowledge, identifying and connecting with appropriate collaborators is not trivial. Open practices can make it easier for researchers to connect by increasing the discoverability and visibility of one's work, facilitating rapid access to novel data and software resources, and creating new opportunities to interact with and contribute to ongoing communal projects.
From 1bd6136baf3c03c600c79ae61a354965339a7bcf Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:42 +0000
Subject: [PATCH 116/142] Update source file open-hardware.md
---
.../open/open-hardware.md | 474 ++++++++++++++----
1 file changed, 376 insertions(+), 98 deletions(-)
diff --git a/book/website/reproducible-research/open/open-hardware.md b/book/website/reproducible-research/open/open-hardware.md
index 50b2d5cd72b..36703e031cc 100644
--- a/book/website/reproducible-research/open/open-hardware.md
+++ b/book/website/reproducible-research/open/open-hardware.md
@@ -1,111 +1,389 @@
(rr-open-hardware)=
-# Open Hardware
-
-"Open hardware", or "open source hardware" [{term}`def`], refers to the design specifications of a physical object that are licenced in such a way that said object can be studied, modified, created, and distributed by anyone.
-Like open source software, the "source code" for open hardware - schematics, blueprints, logic designs, Computer Aided Design (CAD) drawings or files, and the like, is available for modification or enhancement by anyone.
-Users with access to the tools that can read and manipulate these source files can update and improve the physical device and the code that underlies it, and, if they wish, proceed to share such modifications.
-
-Open hardware's source code should be readily accessible, and its components are preferably easy for anyone to obtain.
-Essentially, open hardware eliminates common roadblocks to the design and manufacture of physical goods; it provides as many people as possible the ability to construct, remix, and share their knowledge of hardware design and function.
-
-It is worth noting that open hardware does not necessarily mean free.
-Units may still be sold (by the original designer or by others), but users *could* build them from scratch.
-Whether or not they choose to buy the unit, users can still get a full understanding of how the hardware works from open documentation, designs, and similar.
-
-## Why Open Hardware?
-
-Open hardware allows researchers to understand exactly what their equipment is doing, how it is doing it, and to verify that it is doing it correctly, rather than having to extend a degree of trust.
-Being aware of how the equipment that generates a result works puts researchers on a firmer footing in assessing those results.
-Open hardware also makes research more reproducible as researchers looking to verify results can do the same thing.
-
-Other benefits of open hardware include protection against lock-in.
-Proprietary software for core infrastructure increases the risk of becoming locked in by the vendor or technology.
-If this happens, researchers can be at the mercy of vendors' price increases and experience a lack of flexibility they can not easily and readily escape.
-Further, if researchers want to modify their equipment to better suit their needs it is much easier to do so (and may only be legal) in the case of open source hardware.
-
-## Elements of Open Source Hardware Projects
-
-Here are some files that you should consider sharing when publishing your open source hardware project.
-You are not required to post them all, but the more you share the more the community benefits.
-There is a lot of crossover here with files to include in open source software projects.
-
-### Overview and Introduction
-Your open source hardware project should include a general description of the hardware's identity and purpose, written as much as possible for a general audience.
-That is, explain what the project is and what it is for before you get into the technical details.
-
-### Licence
-An appropriate license on the Open Hardware project and its content grant legal permission to anyone to re-use, modify and distribute the different components of a project according to the terms stated (for example, they must acknowledge your contribution).
-
-### Original Design Files
-These are the original source files that you would use to make modifications to the hardware's design.
-The act of sharing these files is the core practice of open source hardware.
-- Ideally, your open source hardware project would be designed using a free and open source software application, to maximize the ability of others to view and edit it.
-For better or worse, hardware design files are often created in proprietary programs and stored in proprietary formats.
-It is still essential to share these original design files; they constitute the original "source code" for the hardware.
-They are the very files that someone will need in order to contribute changes to a given design.
-- Try to make your design files easy for someone else to understand. In particular, organize them in a logical way, comment complex aspects, and note any unusual manufacturing procedures.
-- Examples of Original Design Files include 2D drawings and computer-aided design (CAD) files.
-
-### Auxiliary Design Files
-Beyond the original design files, it is often helpful to share your design in additional, more accessible formats.
-For example, best practice for an open source CAD design is to share the design not just in its native file format, but also in a range of formats for interchangeable and exportable formats that can be opened or imported by other CAD programs.
-- It is also helpful to provide ready-to-view outputs that can easily be viewed by end-users who wish to understand (but not necessarily modify) the design.
-For example, a PDF of a circuit board schematic.
-These auxiliary design files allow people to study the design of the hardware, and sometimes even fabricate it, even without access to particular proprietary software packages.
-However, note that auxiliary design files are never recommended as substitutes for original design files.
-
-### Additional Technical Drawings
-In their original formats, if required for fabrication of the device, in a commonly-readable format such as PDF.
-
-### Bill of Materials
-While it might be possible to infer from the design files which parts make up a piece of hardware, it is important to provide a separate bill of materials.
-This can be a spreadsheet (for example, CSV, XLS, Google Doc) or simply a text file with one part per line.
-Useful things to include in the bill of materials are part numbers, suppliers, costs, and a short description of each part.
-Make it easy to tell which item in the bill of materials corresponds to which component in your design files: use matching reference designators in both places, provide a diagram indicating which part goes where, or otherwise explain the correspondence.
-
-### Software and Firmware
-You should share any code or firmware required to operate your hardware.
+# Open Source Hardware
+
+## Definition
+
+“Open source hardware” (OSH) refers to the design specifications of a physical object that are licenced such that they and the object can be studied, modified, created, and distributed by anyone.
+Its formal definition [{term}`def`] was written by the open hardware community back in 2010, and is maintained by the [Open Source Hardware Association (OSHWA)](https://oshwa.org), a US-based non-profit.
+
+Translations of *hardware* in some languages may bias the concept towards electronics, but with *hardware* we refer to any physical, tangible object: machines, electronic devices, biomaterials, textiles.
+You will also often see the terms *open hardware* and *open source hardware* used interchangeably in the literature and in this article.
+
+## OSH in Research
+
+
+In 2016, the [Global Open Science Hardware](https://openhardware.science) community took the OSHWA definition and tailored it to the specific needs of science:
+
+> Open Science Hardware (OscH) refers to any piece of hardware used for scientific investigations that can be obtained, assembled, used, studied, modified, shared, and sold by anyone. This includes standard lab equipment as well as auxiliary materials, such as sensors, biological reagents, analog and digital electronic components.
+
+In 2021, the [UNESCO Open Science Recommendation](https://en.unesco.org/science-sustainable-future/open-science/recommendation) became the first policy document to include OSH as a component of open science.
+The recommendation considers open hardware as a pillar of scientific knowledge that should be open.
+
+
+ 
+
+
+
+## What is the source of open source hardware?
+
+Like open source software, the “source code” for open hardware is available for modification or enhancement by anyone.
+In contrast to software, where the source is plain text code, the OSH source is more complex.
+OSH design information refers to:
+schematics, blueprints, logic designs, Computer Aided Design (CAD) drawings or files, and the like (see {ref}`rr-open-hardware-techdoc`).
+It usually entails text, binary files and software.
+
+Importantly, OSH projects should share both raw and derived source files.
+For instance, 3D object designs should be shared as print-ready files (.stl), but also as modifiable 3D objects (the format of these files will depend on the software used).
+It is necessary to provide the raw files to enable modification, even if they can often only be opened in proprietary software, and their use requires specific skills.
+The derived versions are used to build the hardware, but often are not suited for modification.
+Users with access to the tools that can read and manipulate these raw source files can update and improve the physical device.
+If they wish, they can proceed to share such modifications.
+
+
+
+Although OSH projects are diverse in their degree of "openness", best practices in OSH guide us to identify a core, minimum documentation that needs to be in place so others can study, modify, distribute, make or sell our hardware.
+We will go through these various components in the following sections.
+
+
+## Types and phases of open source hardware
+
+```{figure} ../../figures/open-hardware.*
+---
+height: 500px
+name: open-hardware
+alt: 'Illustration showing the life cycle of an open hardware project in research, using seeds and gardening tools as an analogy. The figure shows a circle with six stages surrounding the open hardware logo and gardening tools (a fork, shears and watering can), going clockwise starting on the top. Stage 1 NEED: it represents a researcher thinking about a seed that represent an idea that would solve its problem. Stage 2: Prototyping: Three different seeds are represented, the last one has flowers and roots, which are labeled. This represents the action to try out or "prototyping" different tools to address the need. Stage 3: Selection/Demo: Next to gardening tools, the third prototype is represented as a schematic on a board and a researcher is writing notes. It represents a stage where a prototype can be selected for further development. Stage 4: Documentation: Several boards present separately the roots, the flower and a fork, Six researchers are writing notes about the boards. This represent the inclusion of, these design choices and criteria in the project documentation, so others can follow and learn from the design process. Stage 5: Publishing: An actor is throwing seeds out of a window, another person is receiving the seeds with open arms; on the top we can see three square with labels on it: Reuse, Replicate, Reproduce. This represents the moment a researcher shares openly the designs and documentation of the new device, which can be reused, replicated or reproduce by others to better understand how data was produced. Stage 6: Cultivate ecosystem of open knowledge: A watering can pour water on five plants that are in the soil, two people can be seen on the other side looking at the plants. This represents the hardware commons, the new piece of knowledge can become a building block for others to explore new research questions or scenarios, especially when work is invested in growing a community.'
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
+
+
+
+OSH projects emerge as **a response to a concrete need**, which is reflected in the project lifecycle.
+For example, you may need to process lots of samples, or to measure a parameter you were not considering before, or to take measurements outside of the lab.
+With the analyzing of your need, your OSH project starts.
+It is advisable to scope the project at this point, maybe looking for similar project one can join, instead of starting a new one.
+It may indeed be useful to draw a roadmap, look and find future users, contributors and manufacturers (who may have complementary skills to yours), and decide for a license.
+It is reasonable to invest quite a lot of time in looking for similar projects.
+OSH are often difficult to find and comprehend, but finding projects may save you a lot of time and hassle.
+Indeed, you may learn a lot about your needs, refine your ideas, and may even find collaborators while browsing existing OSH projects.
+
+
+
+You may then test some ideas to address your particular need, which is a process called **prototyping**.
+After many iterations and testing, you will be able to select a prototype for further development.
+The design that solves your need but is not yet complete nor ready to be replicated (usually because some parts are not well documented or requires a lot of manual adjustments) is called a **demonstrator**.
+When the design and documentation are polished and are ready to be used by hardware producers, the hardware is usually labeled as a **market-ready product**.
+
+While many people start generating **documentation** and share their design online at the demonstrator stage, open science enthusiasts advise being open from the beginning of the description of needs phase.
+
+
+There are different degrees for how open an OSH project can be {cite:ps}`Bonvoisin2018`, but every step in this direction is welcome and an opportunity to contribute to better research and open new career paths.
+Designs that are well-documented and offer a solution to a concrete problem can be easily **reused** by others.
+They may **replicate** your design exactly to test it, or **reproduce** it to adapt it to their particular need.
+It is worth thinking about your future self as one of the project collaborators when balancing the resources used in opening and documenting an OSH project, and the resources used to develop the hardware further.
+
+
+In order to make your project more open, one can work on several aspects of open source, which are outlined in the following sections.
+
+
+
+
+# Why should you use or develop open source hardware?
+
+```{figure} ../../figures/why-open-hardware.*
+---
+height: 500px
+name: why-open-hardware
+alt: 'Illustration showing the benefits of using Open Science Hardware for Research and for researchers. On top, the figure shows a cycle divided in two parts, on the bottom, there is a person with short hair surrounded by a microscope, a computer and electronic elements. In its hand, it has a pile of paper lebelled “how to”, which represents the hardware documentation. The lower half circle is labelled “Science” and is surrounded with several half full bechers. Inside the half circle one can read four bullet points: Quality, Reproducibility, Inclusiveness, and Sustainability. The upper half circle is labelled “YOU”, it is surrounded by one person with goggles and earrings. Inside the half circle one can read four bullet points: Flexibility and speed, Price, Control, and Visibility., It represents the benefits of the Open Hardware practice for the individual researcher. These include greater flexibility and speed, as experimental set ups can easily be modified without depending on vendors. Another benefit is price, as open science hardware is today less expensive than available proprietary options. Control is another benefit for the individual researcher, as new features can be included, others removed and set ups completely customized beyond what is established by a third party vendor. Finally, individual researchers gain visibility when they develop their hardware work open, increasing the impact of their work'
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
+```
+
+## For you
+
+People develop and share OSH for a variety of reasons. Particularly in research, OSH provides very concrete advantages:
+
+- Flexibility and Speed: You can quickly customize and combine open designs to test new research questions in an accessible way, instead of depending on vendors, their timelines and bureaucracy.
+
+- Simplicity: As OSH has a lower price tag than conventional equipment, it is much easier to obtain while bypassing the bureaucracy of contracting vendors.
+
+- Control: If a supplier goes out of business, users and/or third party companies have the information to keep systems running.
+
+- Visibility: Researchers and engineers developing OSH make their work more visible to more people.
+ They also increase opportunities for networking and impact, especially in projects involving a community.
+
+- Education: By using open hardware, researchers pick up new skills and can better understand how a certain tool captures data on specific phenomena/events.
+
+
+> It is worth mentioning here that building and developing OSH may require specific knowledge and skills on one hand, and quite a lot of time, on the other hand.
+> Buying industrial hardware with the corresponding client support these companies offer may be cheaper, especially if you do not have enough technical support in house.
+
+
+## For science
+
+- Quality: To make science, we need research instruments; we also need to build on top of others' knowledge.
+ A contributor might offer a totally novel solution to a design problem that would never occur to you; contributors may also catch errors that might have been missed.
+
+- Reproducibility: OSH designs can be replicated, allowing for verification and reproduction of experiments and data.
+ Moreover, users can have much better control on the calibration of their devices, boosting replicability even further.
+
+- Inclusiveness: OSH can make science possible where resources are scarce.
+ Local adaptation and production of OSH helps reducing the impact of import restrictions and bureaucracies that obstaculise science.
+ Also, more students may be able to interact with scientific tools in hands-on sessions, as the equipment is cheaper.
+
+- Sustainability: OSH means you have all the information for repairing and maintaining devices locally, extending the lifespan of the product and reducing waste.
+
+
+Many researchers who develop or use OSH for research also value OSH as an educational tool.
+Working with OSH designs allows students and researchers to fully understand how a certain tool captures data on specific phenomena/events.
+
+
+
+
+
+# How to make hardware open source
+
+
+In order to make your hardware reusable and modifiable by others, its source should be shared with an appropriate license.
+This is usually done via specific online platforms (see {ref}`rr-open-hardware-platforms`.
+The type and amount of shared content depends on the complexity of the OSH, and on the importance of the community aspects of the project.
+
+In the following sections, you can find descriptions of the common types of content that you should consider sharing, such as project documentation, technical documentation, and community interactions.
+You are not required to post or document them all, but the more you share, the more the community benefits, and the more it can give back.
+
+
+There is a lot of crossover with files to include in open source software projects
+(see {ref}`rr-rdm-metadata-documentation`), and the community aspects that are common to any open source project are described elsewhere (see {ref}`pd-overview-repro`)
+
+
+
+
+
+## Project documentation
+
+Your OSH project should at a minimum provide a license {ref}`rr-licensing-hardware` together with a README file with all the basic, general information a newcomer needs to get oriented.
+Include a general description of the hardware’s identity and purpose, written as much as possible for a general audience.
+That is, explain what the project is and what it is for, before you get into the technical details.
+
+
+On top of what is mentioned in detail in the open source project documentation page ({ref}`pd-overview-repro`) for project plan, people involved, and contribution process,
+you should specifically **think about your audience** when writing OSH documentation.
+Indeed,
+your project might be reused by people with different skills, roles, objectives, and socio-economic and cultural environments.
+Because of this it can be useful to create a **list of skills** that are required to build or use the hardware.
+Someone trying to build it from scratch, for example, will require specific set of prior knowledge, skills, and tools.
+A different set is needed to perform maintenance tasks.
+An end user operating the assembled project might require an entirely distinct skillset (and documentation).
+
+**Take particular care about safety instructions. OSH makers are not always formally trained engineers and may not be able to easily differentiate between dangerous and safe manipulations.**
+
+Your project documentation may also include a functional overview of the project's parts or modules, as well as a short description of the software needed to use the hardware.
+Also give an overview of the state of the hardware, software and documentation (current state, ongoing development, and/or any future plans for the project), and other information you think may be useful for newcomers.
+
+
+
+
+
+
+
+
+(rr-open-hardware-techdoc)=
+## Technical documents
+
+Technical documents provide the source needed to study and replicate a hardware design.
+In contrast to project documentation and community building, technical documents for OSH are quite specific, but can be considered analogous to what source code is for software.
+Depending on the project, technical documents may include technical drawings, images describing electronic schematics, computer-aided design ([CAD](https://en.wikipedia.org/wiki/Computer-aided_design)) files, or assembly instructions to replicate the design.
+A thoroughly documented project will have all types of documents.
+It may also include code (firmware and software) necessary to run the hardware.
+The source files (like CAD files) are best accompanied by textual and multi-medial documentation, such as guides for manufacturing, assembly, maintenance, and development.
+
+We provide here a quite exhaustive list of documentation elements.
+Your project may not need all of them, but it is worth considering having at least minimal information for most of these elements:
+
+- A **context description** which may reflect project maturity, complexity, the intentions of authors on how it should be used, and technical specifications.
+ It may include standards compliance (the [DIN-SPEC](https://gitlab.com/OSEGermany/OHS-3105) standard for instance) and an estimation of the overall budget required and build time.
+
+- A **Bill of Materials** (BOM): A list or spreadsheet describing part numbers, putative suppliers, costs, and a short description.
+ Make it easy to tell which item in the bill of materials corresponds to which component in your design files: use matching reference designators in both places, provide a diagram indicating which part goes where, or otherwise explain the correspondence.
+
+- **Assembly instructions**. To help others make and modify your hardware design, you should provide instructions for going from your design files to the working physical hardware.
+It is good to publish annotated photographs (or video) from multiple viewpoints and at various stages of assembly.
+If you do not have photos, posting annotated 3D renderings of your design is a good alternative.
+Either way, it is good to provide captions or text that explain what is shown in each image and why it is useful.
+
+- **Manufacturing instructions**: The manufacturing process of parts that have been made for this project should be documented as well.
+ This is specially important if they are available for purchase from only a handful of small/medium businesses.
+
+- A **list of required tools** and associated settings, for both the software used for development and the machine tools for replication.
+
+- **Design files** with parts metadata, typically including the manufacturing process, the materials with dimensions, mass, and units.
+A functional overview of the project's parts/modules can also be included.
+Ideally, your OSH project would be designed using a free and open source software application, to maximize the ability of others to view and edit it.
+It is essential to share these original design files, in both original and accessible ready-to-view formats.
+The type of parts can also be mentionned with unambiguous reference, between, custom parts (developed as a result of this or another project), off-the-shelf parts (like screws) or (maybe proprietary) complex modules (for example, a single board computer).
+
+- **Software and firmware**: You should share any code or firmware required to operate your hardware.
This will allow others to use it with their hardware or modify it along with their modifications to your hardware.
Document the process required to build your software, including links to any dependencies (for example, third-party libraries or tools).
-In addition, it is helpful to provide an overview of the state of the software (for example, "stable" or "beta" or "barely-working hack").
+In addition, it is helpful to provide an overview of the state of the software (for example, “stable” or “beta” or “barely-working hack”).
+
+- **Instructions for operation and maintenance**: Describe how hardware users should operate the hardware (for example how to calibrate and test it).
+Indicate any maintenance that should be done to secure a good functionality of the hardware.
+
+- **Repair and disposal**: Indicate where or how the hardware can be repaired, and indicate how to dispose or recycle the hardware, if it is beyond repair.
+
+> Note that producing documentation-quality pictures consistently requires adequate tools and setup.
+
+
+## Community documentation
+
+
+While open hardware communities are sometimes different than open software communities, the documentation useful to grow hardware communities are similar to those for a open source project, see the {ref}`pd-overview-repro` chapter. You may want to refer to the {ref}`collaboration` and {ref}`cl-new-community` guide of The Turing Way book for a more detailed description of certain aspects such as practices, metrics, behaviors and observables that can be related to thriving communities.
+
+OSH communities come in all sizes and forms.
+They often develop around people facing similar needs, who realise they will get "something that none of [them] could have developed alone." ([Interview: White rabbit, by the Open make team, Javier Serrano and Amanda Diez Frenandez](https://www.openmake.de/blog/2022/10/20/2022-10-06-interview-white-rabbit/) .)
+We should therefore consider that developing good quality hardware and making it open source already entails an important aspect of community building.
+
+In the following section, we share some considerations about community building for OSH project.
+
+
+
+### Considerations for OSH community building
+
+While scoping your project, it is well advised to think about the different people who may engage with your OSH (see {ref}`cl-stakeholder-mapping`).
+Different OSH projects have included different partners at varying stages of their developement.
+On top of user and contributor roles that OSH have in common with open source software, local or global hardware manufacturers may become important partners of your project.
+You may also think early about the people who will eventually have to maintain and repair the hardware.
+To make it easier for them, it also helps to make your hardware designs modular (splitting your hardware in modules which may have alternative designs).
+Another specificity of hardware may be the importance of the creation of replication tutorials, workshops, seminars, or training materials, which can impact the adoption of hardware designs.
+This is particularly relevant if the OSH is meant to be produced in Do-It-Yourself environments or as a teaching opportunity.
+
+```{note}
+Engineering culture can still be a closed one, not very welcoming to newcomers from different backgrounds.
+
+It is therefore particularly important to Valuing Diversity and Differences in OSH {ref}`cl-new-community-differences`
+
+```
+
+It is important to decide whether, when and where you want to engage with, or build a community.
+Most OSH communities are local in comparison to open source software project.
+You may not have the time or skills to build a community, and your project may not need a community to flourish.
+Always be honest with your collaborators and yourself about what support they can expect.
+The [GOSH forum](https://forum.openhardware.science) has been an enabler for finding collaborators for OSH and OSH-related projects.
+
+
+
+
+
+```{admonition} Learning from community roadblocks
+- It is better to keep an open attitude towards diversification and unstable features, and this does not need to be in conflict with the main project being conservative.
+- There should always be space for "extensions" and "plugins" to be seeded and grow in the same community as the main project.
+3rd-party plugins should be labeled as "external and unsupported by mainline development" but still encouraged.
+- It is good practice to build modular and extensible hardware, with documented interfaces, to be able to grow a developer community.
+- It is a bad idea to respond to a request for help with the following: "It is 'open source', if you want that to happen, you are free to work on it in your own time".
+Be honest of what you can do, but do not be a jerk.
+- If the upstream developers do not have time to write enough documentation, or do not have time to review pull requests, this fact should be stated to avoid generating false expectations.
+- Be ready to delegate (or create new spaces) if you are overwhelmed by a fast-growing community.
+Otherwise, small projects will stall, the community will be frustrated, and then become fragmented.
+```
+
+
+
+
+
+# Sharing open source hardware
+
+One of the goals of making OSH is to share the documentation so others can reuse your project (build upon, improve, derive from).
+Once a project is shared, it can be continuously developed and manintained.
+
+
+For OSH to be effectively adopted, reused, and developed further, the hardware documentation and other relevant information needs to be shared in a way that is easily accessible at no cost.
+The global open hardware community utilizes a variety of platforms and online resources to share their work and enable others to collborate on different projects.
+The details on the some of the platforms used and their efficacy is discussed further in the following section {ref}`rr-open-hardware-platforms`.
+
+(rr-open-hardware-platforms)=
+## Platforms
+
+The easiest way to share an open hardware project is by sharing it online.
+There is no best platform or place to do this, as it depends on the specifics of your project.
+However, some platforms commonly used for OSH are [GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), [Wikifactory](https://wikifactory.com/) and [hackaday.io](https://hackaday.io/).
+Please refer to {ref}`cl-github-novice` for an introduction to GitHub and GitLab.
+Some hardware project have large files, and one may need to look for platforms and workflows allowing to work with big files (see {ref}`rr-vcs-data`).
+
+
+## Making hardware discoverable
+
+
+There is (yet) no straightforward way to let others to know about your project online.
+Here we list some actions you may take in order to
+make your project more visible, reach more people, and improve the chances of reproducibility:
+
+1. Use a commonly used platform; often they have a discovery page and people expect your project to be on such platforms.
+2. Use metadata to discribe your project, apart from just your technical data it is also important to share the metadata of your project, for example a short disciption, a statement of the license, the context of your project.
+Adding a [Open-Know-How manifest](https://www.internetofproduction.org/openknowhow) yaml file may help.
+3. Refer to the guide for communication {ref}`cm-comms-overview` and make a presskit or media content for others to easily share your project on other blogs or websites.
+
+
+In academia, researchers may also **publish** their hardware (usually at the demonstrator stage), as peer-reviewed articles and **archive** a version to generate a DOI.
+
+## Making hardware citable
+
+In contrast to data and software, there is no recommendation for hardware citation yet.
+However, we think it is good practice to treat hardware citation similarly to other research ouptuts {ref}`cm-citable`.
+Making open hardware citable is indeed useful for academic and research output.
+The use of archives that can assign persistent identifiers (DOI) can help to guarantee specific versions/releases of the hardware project available over the long term.
+Though within the open hardware community this is not the practice, it would be beneficial to adopt going forward.
+For research to be reproducible, long term archiving through a platform that is dedicated to it would be necessary.
+
+[Zenodo](https://zenodo.org/) is a good example of the type of archive that can issue a persistent identifier like a DOI.
+Zenodo also has an integration with Github such that projects that are shared and developed there can be archived with ease and a DOI obtained for a specifc version/release.
+
-### Photos
-Photos help people understand what your project is and how to put it together.
-It is good to publish photographs from multiple viewpoints and at various stages of assembly.
-If you do not have photos, posting 3D renderings of your design is a good alternative. Either way, it is good to provide captions or text that explain what is shown in each image and why it is useful.
+## Open source hardware licencing
-### Instructions and Other Explanations
-In addition to the design files themselves, there are a variety of explanations that are invaluable in helping others to make or modify your hardware:
-- Making the hardware: To help others make and modify your hardware design, you should provide instructions for going from your design files to the working physical hardware.
-As part of the instructions, it is helpful to link to datasheets for the components/parts of your hardware and to list the tools required to assemble it.
-If the design requires specialized tools, tell people where to get them.
-- Using the hardware: Once someone has made the hardware, they need to know how to use it.
-Provide instructions that explain what it does, how to set it up, and how to interact with it.
-- Design rationale: If someone wants to modify your design, they will want to know why it is the way it is.
-Explain the overall plan of the hardware's design and why you made the specific choices you did.
-- Limit jargon: Keep in mind that these instructions may be read by someone whose expertise or training is different from yours.
-As much as possible, try to write to a general audience, check your instructions for industry jargon, and be explicit about what you assume the user knows.
-- Format: The instructions could be in a variety of formats, such as a wiki, text file, Google Doc, or PDF.
-Remember, though, that others might want to modify your instructions as they modify your hardware design, so it is good to provide the original editable files for your documentation, not just output formats like PDF.
+A crucial step to making OSH open is by adding an open license.
+Without an open license, others cannot legally use, copy, distribute, or modify that project.
+The situation of hardware licensing is a bit more complex than for research outputs like software, as there are some cases where patent law and not copyright law will apply.
+Also note that you may use different licenses for different part of the project.
-## Open source Hardware Processes and Practices
+Please refer to {ref}`rr-licensing` and {ref}`rr-licensing-hardware`.
-### Designing your Hardware
+Common OSH license are:
-If you are planning to open source a particular piece of hardware, following certain best practices in its design will make it easier for others to make and modify the hardware:
+- [TAPR](https://tapr.org/the-tapr-open-hardware-license/)
+- Similar to GNU GPL 3.0, [SOLDERPAD](http://solderpad.org/)
+- Similar to Apache License 2.0, [CERN-OHL 2](https://ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2) which comes as:
+ - CERN-OHL-S (Strongly reciprocal)
+ - CERN-OHL-W (Weakly reciprocal)
+ - CERN-OHL-P (Permissive).
-- Use free and open source software design (CAD) tools where possible: If that is not feasible, try to use low-cost and/or widely-used software packages.
-- Use standard and widely-available components, materials, and production processes: Try to avoid parts that are not available to individual customers or processes that require expensive setup costs.
+# References/glossary
-### Hosting Your Design Files
-A primary way of sharing your files is with a zip file on your website.
-While this is a great start, it makes it difficult for others to follow your progress or to contribute improvements.
-Using an online source-code repository (like GitHub, GitLab, or NotaBug) may be a better place to store your open source hardware projects.
+Standardisation of Practices in Open Source Hardware by {cite:ps}`Bonvoisin2018`
-### Distributing Open Source Hardware
+This Chapter of the book was created reusing the following documents:
-- Provide links to the source (original design files) for your hardware on the product itself, its packaging, or its documentation.
-- Make it easy to find the source (original design files) from the website for a product.
-- Label the hardware with a version number or release date so that people can match the physical object with the corresponding version of its design files.
-- In general, clearly indicate which parts of a product are open source (and which are not).
+- Open Hardware Academy: https://www.openhardware.academy/03_Lessons.html
+- Open Hardware Makers: https://curriculum.openhardware.space/
+- UKRN primer on open science hardware
From 71179d5918abc700f7cbf0619dc1958b2e2b91ef Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:43 +0000
Subject: [PATCH 117/142] Update source file open-notebooks.md
---
.../reproducible-research/open/open-notebooks.md | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/open/open-notebooks.md b/book/website/reproducible-research/open/open-notebooks.md
index b1439bb0814..6ce0c84c6de 100644
--- a/book/website/reproducible-research/open/open-notebooks.md
+++ b/book/website/reproducible-research/open/open-notebooks.md
@@ -1,7 +1,15 @@
(rr-open-notebooks)=
# Open Notebooks
-Electronic Lab Notebooks (ELNs) enable researchers to organize and store experimental procedures, protocols, plans, notes, data, and even unfiltered interpretations using their computer or mobile device.
+```{figure} ../../figures/executable-notebooks.*
+---
+name: Executable Notebooks
+alt: "Cartoon style with black lines and a light blue accent colour. Two people look at an easel chart depicting a project overview. Below them are the logos of github, Read the docs, jupyter book, and sphinx. Emanating from the project overview are a series of documents with bubbles showing that basing a project around an open exceutable notebook such as a jupyter book allows participants to: Understand the direction/ of the project, Track its progress, Enable diverse participation, Create transparentcy in outcomes, and Make auditing easier for organisers. At the end of the documents there is a globe covered in the speech bubbles of project participants."
+---
+_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.8169292](https://doi.org/10.5281/zenodo.8169292).
+```
+
+{ref}`Electronic Lab Notebooks (ELNs)` enable researchers to organize and store experimental procedures, protocols, plans, notes, data, and even unfiltered interpretations using their computer or mobile device.
They are a digital analogue to the paper notebook most researchers keep.
ELNs can offer several advantages over the traditional paper notebook in documenting research during the active phase of a project, including; searchability within and across notebooks, secure storage with multiple redundancies, remote access to notebooks, and the ability to easily share notebooks among team members and collaborators.
From 96cb37ff66d63cba785cd14d6cad53009e0157e0 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:46 +0000
Subject: [PATCH 118/142] Update source file rdm.md
---
book/website/reproducible-research/rdm.md | 34 ++++++++++++++---------
1 file changed, 21 insertions(+), 13 deletions(-)
diff --git a/book/website/reproducible-research/rdm.md b/book/website/reproducible-research/rdm.md
index 1a7c6ff4804..a1e47fc5703 100644
--- a/book/website/reproducible-research/rdm.md
+++ b/book/website/reproducible-research/rdm.md
@@ -1,13 +1,3 @@
-```{figure} ../figures/data-ecosystem.*
----
-height: 400px
-name: data-ecosystem
-alt: image of the data ecosystem with private and public data
----
-Open and closed data for reproducibility.
-_The Turing Way_ project illustration by Scriberia. Original version on Zenodo. http://doi.org/10.5281/zenodo.3695300.
-```
-
(rr-rdm)=
# Research Data Management
@@ -27,18 +17,36 @@ The following sections in this handbook provide useful context and complementary
Research Data Management (RDM) [{term}`def`] covers how research data can be stored, described and reused.
Data here is used as a generic term to encompass all digital objects.
RDM is a vital part of enabling reproducible research.
-RDM ensures efficiency in research workflows, and also greater reach and impact, as data become FAIR (Findable, Accessible, Interoperable and Reusable).
+RDM ensures efficiency in research workflows, and also greater reach and impact, as data become {ref}`FAIR ` (Findable, Accessible, Interoperable and Reusable).
Data should be stored in multiple locations and backed-up regularly to prevent loss or data corruption.
Clearly describing data using documentation and metadata ensures that others know how to access, use and reuse your data, and also enable conditions for sharing and publishing data to be outlined.
+```{figure} ../figures/data-ecosystem.*
+---
+height: 400px
+name: data-ecosystem
+alt: image of the data ecosystem with private and public data.
+---
+Open and closed data for reproducibility.
+_The Turing Way_ project illustration by Scriberia. Original version on Zenodo. http://doi.org/10.5281/zenodo.3695300.
+```
(rr-rdm-useful)=
## Motivation and Background
+```{figure} ../figures/rdm-storage.*
+---
+height: 400px
+name: rdm-storage
+alt: A cartoon woman standing in front of a very messy closet. She is looking for data that she generated last year. Behind her a person is watching doubtfully, unsure whether she can find it in this mess.
+---
+Research Data Management: making it possible to retreive data from last year.
+_The Turing Way_ project illustration by Scriberia. Original version on Zenodo. http://doi.org/10.5281/zenodo.3695300.
+```
+
- {ref}`Managing your data ` allows you to always find your data and ensure the quality of scientific practice.
- {ref}`Storing your data properly ` and backing-up regularly prevents data loss.
- It can help with {ref}`recognition ` for all research outputs.
- It stimulates **collaboration** with others, who will find it easier to {ref}`understand and reuse your data `.
-- RDM is cost/time efficient, especially if {ref}`shared publicly `, as you will always be able to find and use your data.
-
+- RDM is cost/time efficient (see [Why Does Data Need to be Managed?](https://www.youtube.com/watch?v=C7RZ2t3Cpig)), especially if {ref}`shared publicly `, as you will always be able to find and use your data.
From a585687e19704579b10ad2c4d4667343400a3890 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:46 +0000
Subject: [PATCH 119/142] Update source file rdm-article.md
---
.../reproducible-research/rdm/rdm-article.md | 62 +++++++++++--------
1 file changed, 36 insertions(+), 26 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-article.md b/book/website/reproducible-research/rdm/rdm-article.md
index 37c3c3252db..468b74a3028 100644
--- a/book/website/reproducible-research/rdm/rdm-article.md
+++ b/book/website/reproducible-research/rdm/rdm-article.md
@@ -12,13 +12,13 @@ The benefit of a Data Article is that your output will be {ref}`peer reviewed`.
+You can find out more in our {ref}`subchapter on publishing a data article` or you can read a blogpost on '[What a data paper could do for you](https://ekaroune.github.io/The-Open-Archaeobotanist/2021-01-30-what_a_data_paper_could_do_for_you/)'.
(rr-rdm-article-options)=
## Options to publish a Data Article
Below you can find some journals that publish data articles or papers.
-The costs information was collected in February 2022.
+The costs information was collected in July 2023.
If you are planning to publish an analysis of your published data, it may be worth checking with the journal that they wouldn't consider a data article on that dataset as 'prior publication' (see the [F1000Research (non-exhaustive) list of journals on 'prior publications'](https://f1000research.com/data-policies)).
@@ -28,46 +28,56 @@ If you are planning to publish an analysis of your published data, it may be wor
| Article type| Cost estimate |
| :----: | :----: |
| [Experimental Results](https://www.cambridge.org/core/journals/experimental-results) | [£775](https://www.cambridge.org/core/journals/experimental-results/information/instructions-for-authors#articleprocessingcharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=775&From=GBP&To=USD)) |
-| [Scientific Data](https://www.nature.com/sdata/) | [€1790](https://www.nature.com/sdata/oa) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1790&From=EUR&To=USD)) |
-| [Data in Brief](https://www.journals.elsevier.com/data-in-brief) | [USD 500](https://www.journals.elsevier.com/data-in-brief) |
+| [Scientific Data](https://www.nature.com/sdata/) | [€1890](https://www.nature.com/sdata/oa) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1890&From=EUR&To=USD)) |
+| [Data in Brief](https://www.journals.elsevier.com/data-in-brief) | [USD 530](https://www.journals.elsevier.com/data-in-brief) |
| [China Scientific Data](http://www.csdata.org/) | [RMB 3000 ](http://www.csdata.org/en/p/static/1329/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=3000&From=CNY&To=USD)) |
| [Data Science Journal](https://datascience.codata.org/) | [£650](https://datascience.codata.org/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=650&From=GBP&To=USD)) |
-| [Data](https://www.mdpi.com/journal/data) | [CHF 1400 ](https://www.mdpi.com/journal/data/apc) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1400&From=CHF&To=USD)) |
-| [GigaScience](https://academic.oup.com/gigascience) | [€1089](https://academic.oup.com/gigascience/pages/charges_licensing_and_self_archiving) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1089&From=EUR&To=USD)) |
-| [Gigabyte](https://gigabytejournal.com/information-for-authors)| [USD 350](https://gigabytejournal.com/open-access-and-apc#article-processing-charges) |
-| [F1000Research](https://think.f1000research.com/about-data-notes/) | [USD 800](https://f1000research.com/for-authors/article-processing-charges) |
+| [Data](https://www.mdpi.com/journal/data) | [CHF 1600 ](https://www.mdpi.com/journal/data/apc) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1600&From=CHF&To=USD)) |
+| [GigaScience](https://academic.oup.com/gigascience) | [USD 1209](https://academic.oup.com/gigascience/pages/charges_licensing_and_self_archiving) |
+| [Gigabyte](https://gigabytejournal.com/information-for-authors)| [USD 400](https://gigabytejournal.com/open-access-and-apc#article-processing-charges) |
+| [F1000Research](https://think.f1000research.com/about-data-notes/) | [USD 823](https://f1000research.com/for-authors/article-processing-charges) |
### Discipline specific
| Discipline | Publisher/Journal | Cost estimate |
| :----: | :----: | :----: |
-| Archaeology | [Journal of Open Archaeology Data](https://openarchaeologydata.metajnl.com/) | £100 ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=100&From=GBP&To=USD)) |
+| Agriculture | [Open Data Journal for Agricultural Research](https://odjar.org/) | ? |
+| Archaeology | [Journal of Open Archaeology Data](https://openarchaeologydata.metajnl.com/) | [£350](https://openarchaeologydata.metajnl.com/about/submissions) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=350&From=GBP&To=USD)) |
| Archaeology | [Open Quaternary](https://www.openquaternary.com/about/) | [£300](https://www.openquaternary.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=300&From=GBP&To=USD)) |
| Biodiversity| [Biodiversity Data Journal](https://bdj.pensoft.net/) | [€650](https://bdj.pensoft.net/about#CoreCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=650&From=EUR&To=USD)) |
-| Biodiversity| [BioInvasions Records](https://www.reabic.net/journals/bir/Submission.aspx) | [~€560](https://www.reabic.net/journals/bir/Submission.aspx) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=560&From=EUR&To=USD)) |
-| Biodiversity| [BioRisk](https://biorisk.pensoft.net/about#Author-Guidelines) | [€450](https://biorisk.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=EUR&To=USD)) |
-| Biodiversity| [Biota Colombiana](http://revistas.humboldt.org.co/index.php/biota/about/submissions#authorGuidelines) | 0 |
+| Biodiversity | [BioInvasions Records](https://www.reabic.net/journals/bir/Submission.aspx) | [~€840](https://www.reabic.net/journals/bir/Submission.aspx) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=840&From=EUR&To=USD)) |
+| Biodiversity | [BioRisk](https://biorisk.pensoft.net/about#Author-Guidelines) | [€450](https://biorisk.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=EUR&To=USD)) |
+| Biodiversity | [Biota Colombiana](http://revistas.humboldt.org.co/index.php/biota/about/submissions#authorGuidelines) | 0 |
| Biodiversity |[Check List](https://checklist.pensoft.net/about#Authors-Guidelines) | [€250](https://checklist.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=250&From=EUR&To=USD)) |
-| Biodiversity| [Mycokeys](https://mycokeys.pensoft.net/about#Author-Guidelines) | [variable](https://mycokeys.pensoft.net/about#Article-Processing-Charges)|
-| Biodiversity| [Nature Conservation](https://natureconservation.pensoft.net/about#Author-Guidelines) | [€950](https://natureconservation.pensoft.net/about#Article-Processing-Charges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=950&From=EUR&To=USD)) |
-| Biodiversity| [NeoBiota](https://neobiota.pensoft.net/) | [€950](https://neobiota.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=950&From=EUR&To=USD)) |
-| Biodiversity| [PhytoKeys](https://phytokeys.pensoft.net/about#Author-Guidelines) | [€780](https://phytokeys.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=780&From=EUR&To=USD)) |
-| Biodiversity| [ZooKeys](https://zookeys.pensoft.net/about#SubmissionGuidelines) | [€780](https://zookeys.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=780&From=EUR&To=USD)) |
-| Biology (plant) | [BMC Plant Biology](https://bmcplantbiol.biomedcentral.com/submission-guidelines/preparing-your-manuscript/database-article) | [€2090](https://bmcplantbiol.biomedcentral.com/about) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=2090&From=EUR&To=USD)) |
-| Biodiversity (forest)| [Annals of Forest Science](https://annforsci.biomedcentral.com/submission-guidelines/preparing-your-manuscript/data-paper) | [€1690](https://annforsci.biomedcentral.com/submission-guidelines/fees-and-funding) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1690&From=EUR&To=USD))|
-| Botany | [Botanical Studies](https://as-botanicalstudies.springeropen.com/submission-guidelines/preparing-your-manuscript/database-article) | [€1745](https://as-botanicalstudies.springeropen.com/about) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1745&From=EUR&To=USD)) |
+| Biodiversity | [Mycokeys](https://mycokeys.pensoft.net/about#Author-Guidelines) | [variable](https://mycokeys.pensoft.net/about#Article-Processing-Charges)|
+| Biodiversity | [Nature Conservation](https://natureconservation.pensoft.net/about#Author-Guidelines) | [€950](https://natureconservation.pensoft.net/about#Article-Processing-Charges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=950&From=EUR&To=USD)) |
+| Biodiversity | [NeoBiota](https://neobiota.pensoft.net/) | [€950](https://neobiota.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=950&From=EUR&To=USD)) |
+| Biodiversity | [PhytoKeys](https://phytokeys.pensoft.net/about#Author-Guidelines) | [€780](https://phytokeys.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=780&From=EUR&To=USD)) |
+| Biodiversity | [ZooKeys](https://zookeys.pensoft.net/about#SubmissionGuidelines) | [€780](https://zookeys.pensoft.net/about#ArticleProcessingCharges) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=780&From=EUR&To=USD)) |
+| Biodiversity | [Freshwater Metadata Journal](http://www.freshwaterjournal.eu/) | €0 |
+| Biology | [Open Journal of Bioresources](https://openbioresources.metajnl.com/) | [£350](https://openbioresources.metajnl.com/about#q13) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=350&From=GBP&To=USD)) |
+| Biology (plant) | [BMC Plant Biology](https://bmcplantbiol.biomedcentral.com/submission-guidelines/preparing-your-manuscript/database-article) | [€2390](https://bmcplantbiol.biomedcentral.com/about) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=2390&From=EUR&To=USD)) |
+| Biodiversity (forest)| [Annals of Forest Science](https://annforsci.biomedcentral.com/submission-guidelines/preparing-your-manuscript/data-paper) | [€1750](https://annforsci.biomedcentral.com/submission-guidelines/fees-and-funding) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1750&From=EUR&To=USD))|
+| Botany | [Botanical Studies](https://as-botanicalstudies.springeropen.com/submission-guidelines/preparing-your-manuscript/database-article) | [€1790](https://as-botanicalstudies.springeropen.com/about) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1790&From=EUR&To=USD)) |
+| Crystallography | [IUCrData](https://iucrdata.iucr.org/x/index.html) | [USD 300](https://iucrdata.iucr.org/x/services/openaccess.html) |
| Chemistry | [Journal of Cheminformatics](https://jcheminf.biomedcentral.com/submission-guidelines/preparing-your-manuscript/data-note) | [0](https://jcheminf.biomedcentral.com/about) |
+| Chemistry | [Chemical Data Collections](https://www.sciencedirect.com/journal/chemical-data-collections) | [USD 800](https://www.elsevier.com/journals/chemical-data-collections/2405-8300/open-access-options) |
+| Chemistry | [Food Safety and Risk](https://foodsafetyandrisk.biomedcentral.com/) | [€1890](https://foodsafetyandrisk.biomedcentral.com/submission-guidelines/fees-and-funding) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1089&From=EUR&To=USD) |
+| Chemistry | [Journal of Chemical and Engineering Data](https://pubs.acs.org/journal/jceaax) | [USD 5000](https://acs.chronoshub.io/?q=Journal+of+Chemical+and+Engineering+Data) |
+| Chemistry | [Journal of Physical and Chemical Reference Data](https://pubs.aip.org/aip/jpr) | [3500 USD](https://pubs.aip.org/aip/jpr/pages/charges) |
| Computer Science| [Jaiio](https://www.sadio.org.ar/jaiio/)| [variable](https://50jaiio.sadio.org.ar/aranceles) |
-| Ecology | [Ecological Research](http://www.esj.ne.jp/er/datapaper.html) | [USD 3000](https://esj-journals.onlinelibrary.wiley.com/hub/journal/14401703/homepage/forauthors) |
+| Ecology | [Ecological Research](http://www.esj.ne.jp/er/datapaper.html) | [USD 3000](https://esj-journals.onlinelibrary.wiley.com/hub/journal/14401703/homepage/open-access) |
| Ecology | [Ecology](https://esajournals.onlinelibrary.wiley.com/hub/journal/19399170/resources/types-of-contributions-ecy#Data_Papers) | [variable](https://esajournals.onlinelibrary.wiley.com/hub/journal/19399170/open-access) |
-| Ecology | [Global Ecology and Biogeography](https://onlinelibrary.wiley.com/page/journal/14668238/homepage/forauthors.html) | [€3050](https://authorservices.wiley.com/author-resources/Journal-Authors/open-access/article-publication-charges.html) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=3050&From=EUR&To=USD))|
-| Earth Sciences| [Geoscience Data Journal](https://rmets-onlinelibrary-wiley-com.tudelft.idm.oclc.org/journal/20496060) | [€1450](https://rmets.onlinelibrary.wiley.com/hub/journal/20496060/article-publication-charge) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1450&From=EUR&To=USD)) |
+| Ecology | [Global Ecology and Biogeography](https://onlinelibrary.wiley.com/page/journal/14668238/homepage/forauthors.html) | [USD 4530](https://authorservices.wiley.com/author-resources/Journal-Authors/open-access/article-publication-charges.html) |
+| Earth Sciences| [Geoscience Data Journal](https://rmets-onlinelibrary-wiley-com.tudelft.idm.oclc.org/journal/20496060) | [€1390](https://rmets.onlinelibrary.wiley.com/hub/journal/20496060/article-publication-charge) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1390&From=EUR&To=USD)) |
| Earth Sciences| [Earth System Science Data](https://www.earth-system-science-data.net/) | 0 |
-| Earth Sciences| [Big Earth Data](https://www.tandfonline.com/action/authorSubmission?show=instructions&journalCode=tbed20) | [€910](https://www.tandfonline.com/action/authorSubmission?show=instructions&journalCode=tbed20&#apc) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=910&From=EUR&To=USD)) |
+| Earth Sciences| [Big Earth Data](https://www.tandfonline.com/action/authorSubmission?show=instructions&journalCode=tbed20) | [€790](https://www.tandfonline.com/action/authorSubmission?show=instructions&journalCode=tbed20&#apc) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=910&From=EUR&To=USD)) |
| Ecology | [BMC Ecology and Evolution](https://bmcecolevol.biomedcentral.com/submission-guidelines/preparing-your-manuscript/database-article) | [€2090](https://preview-bmcecolevol.biomedcentral.com/submission-guidelines/fees-and-funding) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=2090&From=EUR&To=USD)) |
| Health | [Open Health Data](https://openhealthdata.metajnl.com/about/submissions/) | [£100](https://openhealthdata.metajnl.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=100&From=GBP&To=USD)) |
-| Humanities | [Journal of Open Humanities Data](https://openhumanitiesdata.metajnl.com/about/submissions/) | [£450](https://openhumanitiesdata.metajnl.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=GBP&To=USD)) |
-| Psychology | [Journal of Open Psychology Data](https://openpsychologydata.metajnl.com/about/submissions/) | [£450](https://openpsychologydata.metajnl.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=GBP&To=USD)) |
+| Humanities | [Journal of Open Humanities Data](https://openhumanitiesdata.metajnl.com/about/submissions/) | [£485](https://openhumanitiesdata.metajnl.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=GBP&To=USD)) |
+| Humanities | [Research Data Journal for the Humanities and Social Sciences](https://brill.com/view/journals/rdj/rdj-overview.xml) | ? |
+| Physics | [Nuclear Data Sheets](https://www.sciencedirect.com/journal/nuclear-data-sheets) | [USD 3900](https://www.elsevier.com/journals/nuclear-data-sheets/0090-3752/open-access-options) |
+| Psychology | [Journal of Open Psychology Data](https://openpsychologydata.metajnl.com/about/submissions/) | [£485](https://openpsychologydata.metajnl.com/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=450&From=GBP&To=USD)) |
| Psychology | [Journal of Cognition](https://www.journalofcognition.org/about/submissions/) | [€1150](https://www.journalofcognition.org/about/submissions/) ([see USD](https://www.xe.com/currencyconverter/convert/?Amount=1150&From=EUR&To=USD)) |
| Zoology | [Arxius de Miscel·lània Zoològica](http://amz.museucienciesjournals.cat/how-it-is-published/?lang=en) | [0](http://amz.museucienciesjournals.cat/editorial-policy/?lang=en) |
From 782a64829d5b7b03f642c40fb1e7b684a6ef336f Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:47 +0000
Subject: [PATCH 120/142] Update source file rdm-data-curation.md
---
.../rdm/rdm-data-curation.md | 29 ++++++++++++++-----
1 file changed, 22 insertions(+), 7 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-data-curation.md b/book/website/reproducible-research/rdm/rdm-data-curation.md
index f8307570ed4..261f03c01de 100644
--- a/book/website/reproducible-research/rdm/rdm-data-curation.md
+++ b/book/website/reproducible-research/rdm/rdm-data-curation.md
@@ -4,9 +4,19 @@
Data curation is one of the key aspects of Research Data Management (RDM).
It involves the capturing, appraisal, disposal, description, preservation, access, reuse and transformation of research data.
Data curation promotes the use of data from the point of creation to ensuring that its used for the purpose it is intended for.
-Data curation also enables you to easily access data sets and information that you need in an organised format, you can easily extract data from whichever repository it is stored.
+Data curation also enables you to easily access datasets and information that you need in an organised format, once shared in a Data Repository [{term}`def`].
You can imagine that if you don't follow the data curation process, it becomes difficult to access that data.
+
+```{figure} ../../figures/data-curation.*
+---
+name: data-curation
+alt: A cartoon illustration describing the seven steps outlined below of the Data Curation Pipeline. The first step is capture, where a person is trying to catch some bugs. The second one is appraisal, where there is a looking glass trying to review the data. The third one is disposal, where some trash is being tossed out of the pipeline. The fourth step is description, which is showing some data charts. The fifth step is preservation, where these charts are then stored in glass jars. The sixth step is access, where individuals would have access to these jars with data in them. The last step is transformation, where different datasets are being transformed into a new one.
+
+---
+The Data Curation pipeline. _The Turing Way_ project illustration by Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807)
+```
+
## Data Curation Pipeline
### 1. Data capture
@@ -14,27 +24,32 @@ Data capture is the process of gathering or collecting data from different sourc
These sources may be research articles in electronic format or databases like electronic databases among others.
This stage focuses on ensuring that the data captured is actually fit for purpose and ready for curation.
+- See {ref}`Finding data` for more information
+
### 2. Data appraisal
-Data appraisal and selection are fundamental stages in the data curation process.
-In data appraisal, you are required to select the appropriate data by entering, digitizing, transcribing, checking, validating and cleaning the data; in addition to anonymizing the data where necessary, describing the data and managing and storing the data.
-As you appraise the data you need to adhere to the documented guidance, policies and legal requirements in evaluating research data in a particular organization and selecting the data that requires long term preservation.
+In data appraisal, you are required to select the appropriate data by entering, digitizing, transcribing, checking, validating and cleaning the data.
+You may also need to anonymise or pseudoanonymise the data where necessary.
Your appraisal and selection policy should ensure consistency, transparency, and accountable decision making.
+- See [Crystal Lewis's blog on cleaning data](https://cghlewis.com/blog/data_clean_02) for more detailed information.
+- Watch [DataONE Webinar: Tidying Your Data](https://vimeo.com/378621271)
+
### 3. Data disposal
Data disposal involves disposing of data that has not be selected for retention.
You need to have an appraisal policy which will guide you on the data required for archiving, redeployment, transfer of custody or ownership or destroying the research data.
### 4. Data description
Data description requires that you are able to interpret the data; derive data; produce research outputs; author publications; data anonymisation; data visualization; data validation and prepare the data for preservation.
-So it is important that you describe the research data so that it is discoverable and usable over time.
+So it is important that you describe the research data so that it is discoverable and usable over time, {ref}`Documentation and Metadata` for more information.
There are also metadata standards that already exist to help you with standardised descriptions.
### 5. Data preservation
-Please find more information in the chapter on {ref}`Data Management Plans`.
+See {ref}`Data Repositories` and {ref}`Sharing and Archiving Data` for more information.
### 6. Data access
Data access entails distributing data, sharing data, publishing data, linking data to outputs, controlling access, establishing copyright and promoting or disseminating the data to wider audiences to access it or re-use it.
-You can make the data freely available online to anyone who may be interested in reading it or you may restrict access of the data or provide an option of how to access the data.
+You can make the data freely available online to anyone who may be interested in reading it or you may restrict access of the data or provide an option of how to access the data.
+See {ref}`Data Repositories` and {ref}`Sharing and Archiving Data` for more information.
### 7. Data transformation
Data transformation is the practice of examining large datasets to generate new information.
From 87dd3f4f9bd15005f5048a60aae01cc3591e6498 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:48 +0000
Subject: [PATCH 121/142] Update source file rdm-dmp.md
---
.../reproducible-research/rdm/rdm-dmp.md | 26 +++++++++++--------
1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-dmp.md b/book/website/reproducible-research/rdm/rdm-dmp.md
index d7921fa996d..4438fb24a54 100644
--- a/book/website/reproducible-research/rdm/rdm-dmp.md
+++ b/book/website/reproducible-research/rdm/rdm-dmp.md
@@ -63,7 +63,7 @@ When in doubt, contact your library Research Data Support Team for more informat
This requires that you address the technological changes, changing user behavior and new requirements on the computer-aided processing of research data as well as evolving organisational.
### 5. Reuse of your research outputs by others
-* Select a license when you make your output available on a repository (see the Licensing subchapters on {ref}`data` and {ref}`software` for more information).
+* Select a license when you make your output available on a repository (see the Licensing subchapters on {ref}`data` and {ref}`software` for more information).
By selecting a license you tell others how they can reuse your data.
If you do not select a license others will not be able to reuse your data without asking you for permission.
* You can put your research outputs into context using and introduction text, such as a README.txt file
@@ -87,22 +87,26 @@ There are several platforms or tools that you can use to set up your Data Manage
* [DMPonline](https://dmponline.dcc.ac.uk)
* [DMPtool](https://dmptool.org)
-
See [activeDMPs](https://activedmps.org/) for a full overview.
## Additional Resources
-- [DataOne education modules](https://www.dataone.org/education-modules)
- [UK Data Services data management information](https://ukdataservice.ac.uk/learning-hub/research-data-management/)
- [TU Delft Research Data Management portal](https://www.tudelft.nl/en/library/research-data-management)
-- [Videos (3-7 min) on data management by Kristin Briney](https://www.youtube.com/watch?v=K5_ocBG5xek&list=PLEor4jq8YPgK_sgEiAcpHZLw-62mufXus)
-- Briney, Kristin. Data Management for Researchers : Organize, maintain and share your data for research success, Pelagic
-Publishing, 2015.
-- Briney, K.A., Coates, H. and Goben, A., 2020 Foundational Practices of Research Data Management. Research Ideas and Outcomes 6: e56508. [https://doi.org/10.3897/rio.6.e56508](https://doi.org/10.3897/rio.6.e56508)
-- Hart EM, Barmby P, LeBauer D, Michonneau F, Mount S, Mulrooney P, et al. (2016) Ten Simple Rules for Digital Data Storage. PLoS Comput Biol 12(10): e1005097. [https://doi.org/10.1371/journal.pcbi.1005097](https://doi.org/10.1371/journal.pcbi.1005097)
-- Video on [elements of a DMP](https://commons.esipfed.org/node/1442).
+- [Research Data Management](https://www.scienceeurope.org/our-priorities/research-data/research-data-management/) by Science Europe
+- Books
+ - {cite:ps}`Briney2015dmp`
+- Articles
+ - {cite:ps}`Briney2020dmp`
+ - {cite:ps}`Hart2016dmp`
+ - {cite:ps}`Michener2015dmp`
+- Videos
+ - [Videos (3-7 min) on data management by Kristin Briney](https://www.youtube.com/watch?v=K5_ocBG5xek&list=PLEor4jq8YPgK_sgEiAcpHZLw-62mufXus)
+ - Video on [elements of a DMP](https://commons.esipfed.org/node/1442).
+ - [3 min video on Roles and Responsibilities](https://www.youtube.com/watch?v=Ry0OA9mDTCc )
+ - [DMPs by DTU Bibliotek](https://www.youtube.com/watch?v=tvs5_X5rn8w) (20 minutes)
+ - [Areas of a Data Management Plan](https://www.youtube.com/watch?v=L3LPv2sB-IE) (7 minute video by Moore Library)
- Definition of [Long Term Preservation](https://www.gesis.org/en/research/research-data-management/long-time-preservation) from the Leibniz Institute of Social Science.
-- [Video (20 min) on DMPs by DTU Bibliotek](https://www.youtube.com/watch?v=tvs5_X5rn8w)
- Planning by [DataOne](https://dataoneorg.github.io/Education/bp_step/plan/) & [USGS](https://www.usgs.gov/data-management/planning)
-- [Areas of a Data Management Plan](https://www.youtube.com/watch?v=L3LPv2sB-IE) (7 minute video by Moore Library)
+
From 28c50579ba08395928fee9a49ff647134002b93e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:48 +0000
Subject: [PATCH 122/142] Update source file rdm-elns.md
---
.../reproducible-research/rdm/rdm-elns.md | 262 ++++++++++++++++++
1 file changed, 262 insertions(+)
create mode 100644 book/website/reproducible-research/rdm/rdm-elns.md
diff --git a/book/website/reproducible-research/rdm/rdm-elns.md b/book/website/reproducible-research/rdm/rdm-elns.md
new file mode 100644
index 00000000000..3683fca43d7
--- /dev/null
+++ b/book/website/reproducible-research/rdm/rdm-elns.md
@@ -0,0 +1,262 @@
+(rr-rdm-elns)=
+# Electronic Lab Notebooks
+
+An Electronic Laboratory Notebook (commonly known as an ELN or a digital lab notebook) is a software system designed to help you document and maintain reproducibility of your research and share information more easily.
+ELNs enable researchers to organize and store experimental procedures, protocols, plans, notes, data, and even unfiltered interpretations using their computer or mobile device.
+They can be a digital analogue to the paper notebook most researchers keep.
+ELNs can offer several advantages over the traditional paper notebook in documenting research during the active phase of a project, including; searchability within and across notebooks, secure storage with multiple redundancies, remote access to notebooks, and the ability to easily share notebooks among team members and collaborators.
+ELNs make the practice of {ref}`open notebooks ` [{term}`def`] practical in a way that it is not for paper lab books.
+However, it is important when choosing an ELN solution to avoid giving up the advantages offered by a paper lab notebook.
+
+(rr-rdm-elns-procon)=
+## Quick Pros & Cons of ELNs
+
+Electronic Lab Notebooks may provide, among other things, the following **functionalities**:
+
+* A text editor with similar functions as a paper notebook
+* A search function
+* Secure storage and back up (with distinct failure modes from paper notebooks)
+* Tools for working with tabular data (calculations and formatting of tables and graphs)
+* Templates for documenting standard procedures
+* Built-in Laboratory Inventory Management Systems (LIMS) functionality for managing and documenting samples, reagents, and apparatus, or integration with separate dedicated LIMS.
+* Collaboration tools for sharing experimental information
+* Some ELNs will allow you to comply with standards and regulations because of their certification processes
+
+ELNs also have their **limitations**:
+
+* **Costs**: Most ELN solutions can only be used through paid plans, or the free plans have reduced functionalities in the number of users, storage space or file sizes.
+Your lab may also not have access to tablets or pens that would make the use of ELNs easier.
+Check if your institution is offering a solution that you can use without additional costs.
+* **File format**: Always check if files can be exported in your preferred file formats to avoid format lock-in.
+Some ELNs also have API's that allow integration with other software and workflows.
+* **{ref}`Vendor-lock-in`**: Once you're using a certain solution you may become dependent on it.
+Always have an exit strategy in case the solution is no longer offered or if you're moving institutions and you no longer have access.
+* **Sustainability**: Choose a solution that has a larger chance of being around for a long time.
+* **Drawing**: Not all solutions have the tools or capabilities to include drawings or integration with drawing software.
+* **Security**: Before using an ELN solution you should check any backup plans and data security measures, especially if you're working with sensitive data.
+* **Laboratory situation**: Your lab may not have an internet connection or electronic tools could affect samples, reagents or magnets in the lab.
+* **Learning curve**: ELNs have a longer learning curve than paper notebooks and it takes time to learn how to use them.
+User-friendliness and flexibility are important to accommodate the widely varying workflows of each lab member.
+
+(rr-rdm-elns-choosing)=
+## Choosing an ELN solution
+
+If you are in a position to choose an ELN to use, or are making a choice on behalf of an organisation there are some factors to consider:
+
+(rr-rdm-elns-choosing-importance)=
+### Importance of getting it right
+
+Many organisations offer software that purports to solve the problem of ELNs.
+So choosing a suitable solution can be a major headache and responsibility.
+The choice of ELN is an incredibly important decision, and one that your organisation will likely have to live with for years, or even decades.
+You are putting the record of your research into the hands of the tool that you choose, and entering into a long-term relationship with the provider of your ELN solution.
+You are also making a choice about a tool that many of the people in your organisation will interface with closely every day.
+Having to use a tool that is not well fit to its function on a daily basis can be a major problem for productivity and morale.
+Conversely, a tool that is a good fit gets out of people's way and makes their jobs easier can be a major boost to productivity and morale.
+
+(rr-rdm-elns-choosing-failure-modes)=
+### Failure modes in user adoption of ELNs
+
+Incomplete or inflexible ELN solutions which increase friction in workflows can cause issues.
+People will avoid using ill-fitting tools that they perceive to be getting in their way, especially scientists.
+They are creative, stubborn, resourceful, and impatiently focused on answering their research questions with whatever tools are available to them.
+Finding software with the flexibility, capability, and scope to keep up is not easy and if it doesn't researchers won't use it - at least not as you intended.
+
+- Shadow IT/notebooks
+ - People using their own unsanctioned solutions which may be a compliance issue and introduce risks that you have not accounted for
+- Infrequent updates
+ - People dump a copy of their work into the ELN only as often as necessary for compliance
+- Consistency issues
+ - If there are paper and potentially multiple electronic copies of some information - what happens when it does not agree? What is the source of truth?
+- Sprawl
+ - Partial adoptions can lead to different pieces of information being stored in different systems which might not be connected making it harder to record and find information which was previously in one place.
+ This can make information recording and retrieval processes more complex, expensive and brittle
+- Practical use and interface issues
+ - Laptops or tablets can introduce interface barriers
+ - Lab gloves may hamper the use of touchscreens and track pads
+ - Free-hand drawing is not always well supported which can be necessary when using notation that is not easily represented in simple text such as mathematical and chemical notation
+ - Client issues, such as native mobile applications with incomplete featuresets, slow web-apps that may require an always-on connection and not be able to cache local changes
+ - No spatial memory, whereas in a physical book people may remember where they wrote things and can open it roughly on the right page
+ - Extra expense, maintenance and procurement issues with hardware suitable for use in your research environment
+
+- Lack of sufficiently available training on more complex aspects of the ELN solution leading to poor, mis-use, or under-use of ELN features
+
+(rr-rdm-elns-choosing-compare-to-paper)=
+### Always compare to paper notebooks
+
+When picking an ELN remember to always compare the ELN to a paper notebook and not just to other ELNs.
+It is likely paper that you are replacing so this is the benchmark against which to compare.
+Consider the differences between a paper copy of a lab notebook and an electronic copy.
+Consider also which properties of a paper copy is it important to you that you are able to retain when adopting an electronic alternative.
+
+- A paper lab notebook is physically under your control.
+- You (or more likely your organisation) own it.
+- You can control access to it physically.
+- Your physical possession of this resource means that it would be difficult for anyone to prevent you from accessing it.
+- Conversely it must be physically stolen to be accessed by a malicious third party.
+- On the other hand, ELNs - like all software - have security vulnerabilities.
+- You are not dependent on the functioning of any complex systems like computer networks in order to be able to use your paper lab notebook.
+- You do not need any specialist tools in order to access its contents.
+- There is no reason why you might have to pay a third party a fee in order to continue using it.
+- You do not have to agree to a 'terms of service' or 'end-user license agreement' with a third party to use and retain access to your lab book. These terms may be subject to unilateral alteration by that third party.
+
+If your provider of paper lab books goes out of business it has almost no bearing on your ability to continue doing your work.
+One paper notebook is much like another, finding a new provider is pretty easy.
+Changing providers does not impact on your ability to access your past notebooks or to continue operating with the same workflow in future ones.
+This is not necessarily true of ELNs.
+
+(rr-rdm-elns-choosing-archival)=
+### Archival function of notebooks
+
+Lab notebooks perform an archival function.
+Few active measures are needed to maintain the data in your paper notebooks.
+The primary vulnerability of paper lab books is that there is only one copy.
+Nevertheless, as long as they are kept in a cool, dry and dark spot (for example a fireproof safe) they will likely last decades.
+
+Electronic data requires much more active upkeep.
+Electronic data can, *if managed properly*, be more resilient to physical threats such as fire and flooding as it can frequently be backed up in multiple locations.
+A hard drive, or even a solid state drive, however, cannot be left in a draw for a decade or more and have a high likelihood of working without some amount of bit-rot or compatibility issues when plugged back in.
+
+For digital data it is important for archiving and maintaining the data to use formats that maximize the likelihood of recovering relevant information.
+Proprietary formats are antithetical to this.
+Proprietary solutions generally obfuscate the format, even if just through absense of generally available specifications and documentation.
+Proprietary formats generally have a single implementation from their creator, this creates a single point of failure.
+Open formats can have multiple different implementations of tools which read them.
+If there is a good enough specification then new tools can even be written for the format if none of the originals are available anymore.
+Proprietary tools may require some kind of license activation process to use this may not be possible if their vendor no longer exists.
+Using a proprietary solution for archival purposes is therefore taking a needless risk with the future of your data.
+Your data's fate is tied to the format in which it is stored so choose it wisely.
+
+(rr-rdm-elns-choosing-lockin)=
+### Lock-in
+
+Most proprietary or open tools will permit you to export your data in one format or another.
+The quality of this export is critical to scrutinise.
+The ability to save all your lab books as PDFs is fine but if it is the only option you may lose a lot of metadata, and the ability to import your data into a new solution.
+The ability to export your data and retain the original structure is very important to evaluate.
+
+Proprietary solutions are incentivised to attempt to lock-in their customers so that the cost of switching to a competitor is high - so be especially wary of poor export options.
+Note that this tends to change over time.
+New providers are focused on user acquisition so data portability is often good at first but tends to decline after a certain point in time.
+Firms tends to follow a pattern of shifting from a user acquisition phase with favourable terms, to a user retention phase with less favourable ones.
+Mendeley for example began [encrypting their local database](https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption).
+This made it impossible to migrate your local library to different reference managers without going through the Mendeley online library feature.
+This occurred after they had reached a high degree of market penetration and had been acquired by Elsevier.
+
+When looking for any critical piece of software for long term use the first questions to ask are:
+- Is there an Libre / open-source solution to this problem?
+- If it is a web app and/or has a server: Could I host my own fully featured instance, should I need to?
+- Is there a large/active community using the project, does it have institutional backing of some kind?
+ This might take the form of a company which sells service contracts, or offers paid hosting ideally with feature parity with a self-hosted option.
+ Or perhaps a foundation or other non-profit/academic organisation with robust funding.
+- What are the data export options and formats?
+
+Open solutions provide you with the assurance that if you do the appropriate preparatory work you should be able to access all of your data in its native form.
+For example keeping copies of the ELN software that can be run offline in a virtual machine (VM) or similar computational environment in the future.
+This is typically much easier for open applications and can be impossible for proprietary ones.
+Even if the tools are no longer maintained they can still be used to read the data and interact with it in (mostly) the same way.
+The data will also likely be stored in an open format from which it can relatively easily be extracted and ported to a new format.
+This may still be a lot of work but it is much more attainable than reverse engineering a proprietary format for which there is no documentation, or worse - dealing with encrypted files.
+
+You can pay for third party hosting and administration of open source applications.
+This is a solution when you don't have the expertise or internal resources to administer a self-hosted instance of an open-source ELN solution.
+In this case you get the best of both worlds: the benefits of professional support and the reassurance of an open solution.
+You should still take regular local backups of exports from your hosting provider from which you could restore your ELN system with different hosting.
+This means that you retain the option to change providers.
+Conventional Software as a Service (SaaS) platforms are highly vertically integrated: the software development, hosting, administration, and support are package deal that you must take or leave as is.
+When using open tools each of these layers can separated, though they do not need to be.
+This gives you the flexibility to change your provider of any of them independently.
+This improves your bargaining position, but may increase procurement complexity.
+
+(rr-rdm-elns-choosing-automation)=
+### Automation and integration
+
+ELNs with APIs have the potential for integration with instruments that would permit direct deposition of data from connected instruments into ELNs or other connected research data management infrastructure.
+These sorts of integrations are especially useful in workflows at core facilities.
+For example, bioimaging facilities can automate a substantial part of the image metadata deposition into image data management tools such as [OMERO](https://www.openmicroscopy.org/omero/).
+
+(rr-rdm-elns-standards)=
+## ELN standards and project governance
+
+ELNs offer many advantages over paper notebooks.
+Nevertheless, ELNs come with a considerable amount of additional complexity and additional risks - so it is important to have a mitigation plan.
+The ELN space is still quite young and rapidly changing.
+As such it is important to think about how the academic community wants the ELN infrastructure to be owned and governed in the long run.
+An interesting model to consider emulating here is [moodle](https://moodle.com/), an open source electronic learning environment popular with universities.
+It offers commercial support and hosting and has a network of developers across the education sector who contribute to the core project, as well as creating custom integrations and extensions to meet their particular needs.
+This structure allows institutions to pool resources to fund the development of features that they all need and keeps this infrastructural code in common ownership, avoiding the worst lock-in issues arising from the use of proprietary solutions.
+This more open distributed model also allows individuals to work on their own custom extensions and integrations instead of being reliant on the ability and willingness of a company to implement a feature that you need.
+
+Without an open standard even if you are using an open source ELN and/or open file format this does not mean that you will necessarily be able to easily use your data with other ELN tools.
+Such a standard would, if properly adhered too, reduce the lock-in risk associated with using both open and proprietary tools.
+An initiative to devise ELN format standards would be most welcome.
+
+(rr-rdm-choosing-elns)=
+## Resources for choosing ELNs
+
+- [How to pick an electronic laboratory notebook](https://doi.org/10.1038/d41586-018-05895-3) by {cite:ps}`Kwok2018eln`
+- [2019 Review of the Best Electronic Laboratory Notebooks](https://app.scientist.com/blog/2019/04/05/2019-review-of-the-best-electronic-laboratory-notebooks).
+- [Guide on choosing an ELN from Simon Bungers of Labfolder](https://labfolder.com/electronic-lab-notebook-eln-research-guide/).
+- The Harvard Longwood Medical Area Research Data Management Working Group Constructed an [Electronic Lab Notebook Comparison Matrix](https://doi.org/10.5281/zenodo.4723753) in 2021, for convenience [a nicely formatted google sheet version](https://docs.google.com/spreadsheets/d/1ar8fgwagOh30E31EAPL-Gorwn_g6XNf81g3VDQnQ_I8/edit#gid=0), is also available.
+- This recent review {cite:ps}`higgins2022elns` provides a good overview of considerations when adopting an ELN solution.
+ It covers such things a regulatory compliance that is not yet touched on here.
+ It does occasionally appear to conflate open-source solutions with self-hosted ones which need not necessarily be the case.
+ Some companies will let you host proprietary apps on premises.
+ It is also possible to pay for third party hosting and administration of open source applications.
+* [ELN finder](https://eln-finder.ulb.tu-darmstadt.de/home) a tool to select an ELN suitable for your purposes
+
+(rr-rdm-eln-open-elns)=
+## Select Open Infrastructure ELN Options
+
+The following ELN options are each quite different but have many of the same core features.
+
+* [eLabFTW](https://www.elabftw.net/)
+ * Has features such as: Laboratory resource scheduling feature for booking things like hoods and microscopes, automatic mol file previews for molecules and proteins, and support for free-hand drawing.
+ * eLabFTW has a [website](https://www.elabftw.net/), [documentation](https://doc.elabftw.net/) and there is a [demo](https://demo.elabftw.net/login.php) deployment that you can try out.
+ * Self-hosting is *relatively* simple [according to the documentation](https://doc.elabftw.net/install.html).
+ There is also a [paid support tier](https://www.deltablot.com/elabftw/) which would be recommend for any larger deployment to support the ongoing development of the project.
+ * [Paid cloud hosting](https://www.deltablot.com/elabftw/) is available from the developer in a geographical region suited to your needs.
+ A more expensive tier with hosting in France compliant with additional security and privacy certifications is available.
+
+* [openBIS](https://openbis.ch/)
+ * Robust features for integrated metadata management, for example, linking to ontologies / controlled vocabularies.
+ * openBIS has an API and can integrate with Jupyterhub for Electronic Lab Notebooks.
+ * Complete LIMS where storage is integrated with protocols and experiment records, including keeping track of bar-coded stocks.
+ * You can get a feel for it in the [demo](https://openbis-eln-lims.ethz.ch/openbis/webapp/eln-lims/) deployment.
+ * openBIS is a bit more complex to administer [based on its documentation](https://openbis.ch/index.php/docs/admin-documentation/).
+ * As openBIS is developed at ETH Zurich it can be hosted for you under the openRDM service operated by ETH Zurich scientific IT services.
+ No fixed pricing is available - cost would be dependent on your specific needs.
+
+* [OSF](https://osf.io/)
+ * OSF is oriented towards sharing and collaborating on your work, including the ability to generate DOIs and host pre-prints directly on the main instance.
+ See {ref}`OSF` for more information.
+ * It is free to use OSF at the main instance at [osf.io](https://osf.io/).
+ For larger data you must provide your own additional [storage add-ons, available from a number of cloud storage providers](https://help.osf.io/article/395-storage-add-ons).
+ * Whilst you could deploy your own self-hosted OSF this is not how it is intended to be used (except for development).
+ * The OSF has strong sharing features, making it easy to share parts of your ELN publicly.
+
+When using an open solution it is always important to consider how you can contribute to its ongoing development and maintenance, for example by donating to the project.
+If it makes sense given the makeup of your organisation and that of the project you may also be able to contribute developer time to the project.
+
+(rr-rdm-using-non-elns-for-eln-things)=
+## Using non-ELNs for ELN things
+
+Note taking and personal knowledge management (PKM) applications of various kinds have been pushed into service as ELNs by many individuals and institutions, despite not being designed specifically for this task.
+Some tools are better suited to be used 'off-label' as ELNs than others.
+Some may have significant drawbacks compared to purpose built solutions, despite being better at some things than currently available dedicated ELN options.
+
+Microsoft OneNote is quite popular as an ELN despite a proprietary notebook format with limited export options and that [Microsoft has entertained getting rid of the good (desktop) version this of application in favour of its much less featureful 'web' version in the past. Though they have apparently relented, for now](https://www.youtube.com/watch?v=4IkUfh05TGE).
+OneNote is a good experience as a free-form note taking tool especially for hand-written or drawn notes and automatic linking of annotations to audio timestamps.
+The lack of a good version history is a distinct downside.
+Its popularity likely stems, in part, from its availability in the Microsoft Office suite (software already provided by institutions which do not incur additional costs).
+
+Other generic note taking applications have featuresets which are not dissimilar to ELN solutions.
+For example, open source applications like [logseq](https://logseq.com/) or [zettlr](https://www.zettlr.com/), and proprietary ones like: [obsidian](https://obsidian.md/) or [notion](https://www.notion.so/).
+
+(rr-rdm-additional-eln-resources)=
+## Additional ELN resources
+
+* [Electronic Lab Notebooks: can they replace paper?](https://doi.org/10.1186/s13321-017-0221-3) by {cite:ps}`Kanza2017eln`
+* [Electronic Lab Notebooks](https://datamanagement.hms.harvard.edu/collect-analyze/electronic-lab-notebooks) by Harvard Medical School
+* [RSpace](https://www.researchspace.com/)
+
From d3a99b93b53ff8c8100cef307f677bff49a16781 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:49 +0000
Subject: [PATCH 123/142] Update source file rdm-fair.md
---
book/website/reproducible-research/rdm/rdm-fair.md | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/book/website/reproducible-research/rdm/rdm-fair.md b/book/website/reproducible-research/rdm/rdm-fair.md
index 5a6c450820b..333549d3524 100644
--- a/book/website/reproducible-research/rdm/rdm-fair.md
+++ b/book/website/reproducible-research/rdm/rdm-fair.md
@@ -47,6 +47,16 @@ It is also important to say that the FAIR principles are aspirational: they do n
The FAIR principles are also applied to software (see [[LGK+20](https://the-turing-way.netlify.app/afterword/bibliography.html#id10)]and [[HCH+20](https://the-turing-way.netlify.app/afterword/bibliography.html#id9)]). Watch a [ten minute video on FAIR software](https://www.youtube.com/watch?v=ME8_NRGRhSs&list=PL1CvC6Ez54KDvJbbdLn5rPvf1kInifEh9&index=16) for a short explanation.
+## FAIR principles and environmental sustainability
+
+> "FAIR practices can result in highly efficient code implementations, reduce the need to retrain models, and reduce unnecessary data generation/storage, thus reducing the overall carbon footprint.
+> As a result, green computing and FAIR practices may boht stimulate innovation and reduce financial costs." - {cite:ps}`Lannelongue2023greener`
+
+## FAIR principles and accessibility
+
+The Accessible in FAIR is not equal to ensuring that your research objects are accessibles to all users.
+For this, the term “actually accessible” has been coined by {cite:ps}`Colon2023accessibility` to refer to data that is "easy to locate, obtain, interpret, use, share, and analyze for everybody, including disabled people."
+
(rr-rdm-fair-community)=
## Community involvement
@@ -65,3 +75,5 @@ There are two global initiatives that act as umbrella organisations and referenc
* Under GOFAIR, there are many [Implementation Networks (INs)](https://www.go-fair.org/implementation-networks) committed to implementing the FAIR principles.
* Under the RDA, there are several groups tackling different aspects relevant to the RDM life cycle. Among these, one group, the [FAIR Data Maturity Model Working Group](https://www.rd-alliance.org/groups/fair-data-maturity-model-wg) is reviewing existing efforts, building on them to define a standard set of common assessment criteria for the evaluation of FAIRness.
+## More information
+- Deep dive into the [FAIR principles by Dr. Maryann Martone](https://www.youtube.com/watch?v=xx2wHxQfcnA) (45 minute video)
From bed1209d0b9af69ccb5e3f446a24074ecc87480e Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:49 +0000
Subject: [PATCH 124/142] Update source file rdm-find.md
---
.../reproducible-research/rdm/rdm-find.md | 74 +++++++++++++++++++
1 file changed, 74 insertions(+)
create mode 100644 book/website/reproducible-research/rdm/rdm-find.md
diff --git a/book/website/reproducible-research/rdm/rdm-find.md b/book/website/reproducible-research/rdm/rdm-find.md
new file mode 100644
index 00000000000..31475e20b5f
--- /dev/null
+++ b/book/website/reproducible-research/rdm/rdm-find.md
@@ -0,0 +1,74 @@
+(rr-rdm-find)=
+# Finding Data
+
+There is an enormous amount of research data now out there online, either openly available or restricted.
+Despite the amount of data available, finding the right data for your research project/question is often difficult.
+The tips below may help you in finding data suitable for your project.
+
+You also need to consider if data is actually reusable - does it have the correct license?
+And does it contain enough metadata and documentation for reuse?
+
+(rr-rdm-find-data)=
+## Finding a dataset
+
+You can find open and restricted datasets by conducting searches of the metadata such as keyword searches.
+
+You can find data via:
+* Direct browsing of discipline-specific and multidisciplinary repositories such as Zenodo, Open Science Framework, Figshare.
+ * Search for discipline-specific data repositories on [Re3data](https://www.re3data.org/), [FAIRsharing](https://fairsharing.org/) or look at this list of [data repositories](https://oad.simmons.edu/oadwiki/Data_repositories).
+ * See {ref}`Data Repositories ` for more information.
+* Search in data journals and research articles - you can start by looking at our {ref}`Chapter on Data Articles`.
+* Use your network to find datasets.
+* Use specific data search tools:
+ * [B2FIND data search](http://b2find.eudat.eu/)
+ * [BASE](https://www.base-search.net/)
+ * [DataCite Metadata Search](https://search.datacite.org/)
+ * [Europäisches Datenportal](https://www.europeandataportal.eu/de)
+ * [Google Dataset Search](https://datasetsearch.research.google.com/)
+ * [EOSC Portal](https://eosc-portal.eu/) and search the [data catalogue](https://search.marketplace.eosc-portal.eu/search/dataset?q=*&standard=true&exact=false&radioValueAuthor=A&radioValueExact=A&radioValueTitle=A&radioValueKeyword=A).
+
+(rr-rdm-find-license)=
+## Check the license
+
+Once you found a dataset, you need to check the license to see if you can actually reuse the data!
+
+The most commonly used open licences are [Creative Commons](https://creativecommons.org/choose/), [Open Government Licence](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/), or an [Open Data Commons Attribution License](https://opendatacommons.org/licenses/by/index.html).
+See our {ref}`Chapter on Licensing` for more information.
+
+Not all datasets that are available to researchers are open datasets.
+Therefore, if you want to use a restricted dataset, you need to check how you can apply to access it and what the restrictions are on its use.
+Use of restricted datasets is more likely to have a cost so plan for these costs in advance.
+Restricted datasets still have a license on them and there should be a clear application process such as a data request form or an email address to inquire about the access.
+
+(rr-rdm-find-metadata)=
+## Check the metadata and documentation for reusability
+
+After a metadata check to see if the data is of use to you, you'll need to evaluate the dataset more closely.
+
+The following questions may help you to do so:
+
+* What was the original research question?
+* How was the data collected?
+* Are the collection and processing methods appropriate to answer my research question?
+* Is the data collection process well documented? Which instruments were used? What settings/parameters?
+* Are protocols of the data collection shared?
+* Is there sufficient information available to understand the dataset and its context/origin?
+* Is the information complete, understandable and consistent?
+
+(rr-rdm-find-credit)=
+## Giving credit for use of data
+
+Once you have used someone elses dataset, you'll need to cite the data to provide credit to the original data creator(s)!
+
+You need to do this clearly in your research documentation as well as in any research articles you publish.
+See {ref}`Citing Research Objects` for more information about how to properly cite datasets.
+
+Always check how the original dataset should be cited: sometimes researchers want you to cite the accompanying publication instead of the dataset itself.
+This information is generally available in READme files or in the metadata of the repository.
+
+
+(rr-rdm-find-info)=
+## More information
+
+* [Eleven quick tips for finding research data](https://doi.org/10.1371/journal.pcbi.1006038) by {cite:ps}`Gregory2018finddata`
+
From 4aceaf407c9e87bb13d7244891185bacc63389df Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:50 +0000
Subject: [PATCH 125/142] Update source file rdm-metadata.md
---
.../reproducible-research/rdm/rdm-metadata.md | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/book/website/reproducible-research/rdm/rdm-metadata.md b/book/website/reproducible-research/rdm/rdm-metadata.md
index 8517bcc9474..a82faa92afd 100644
--- a/book/website/reproducible-research/rdm/rdm-metadata.md
+++ b/book/website/reproducible-research/rdm/rdm-metadata.md
@@ -56,6 +56,20 @@ In this case, a text file with discipline specific metadata can be added as part
Want to learn more about Metadata and Metadata Standards? Watch an [introduction video](https://commons.esipfed.org/node/1422).
+
+(rr-rdm-metadata-tagging)=
+## Tagging
+
+Tags are keywords assigned to files, and a way to add metadata to a file to organise them more flexibly.
+While a file can only be in one folder at a time, it can have an unlimited number of tags.
+
+Some tips include:
+- Use short tag names (one or two words)
+- Be consistent with tags
+- Not all file formats allow tags, and when files are transferred tags may be stripped
+
+See [Tagging and Finding Your Files by MIT libraries](https://libguides.mit.edu/metadataTools)) for more information.
+
(rr-rdm-metadata-resources)=
## Additional Resources
- Videos on [Data Description](https://www.youtube.com/watch?v=sg3P_V8PIes) & [Documentation and Data Quality](https://www.youtube.com/watch?v=3ByfQWDcavg) from the [TU Delft Open Science MOOC](https://online-learning.tudelft.nl/courses/open-science-sharing-your-research-with-the-world/).
@@ -63,3 +77,5 @@ Want to learn more about Metadata and Metadata Standards? Watch an [introduction
- [Webinar: The Data You Document are the Data We Love](https://youtu.be/SoFxBN-Jnbg?t=1133)
- [Slides: FAIRify your data: data documentation and metadata](https://osf.io/wbr7t/)
- [Controlled vocabularies for the social sciences: what they are, and why we need them](https://odissei-data.nl/en/2022/10/controlled-vocabularies-for-the-social-sciences-what-they-are-and-why-we-need-them/)
+- [Research Data Management: Metadata](https://libguides.ucd.ie/data/metadata)
+- Data dictionaries and codebooks by {cite:ps}`Buchanan2021dictionaries`.
From 836b59f741047324513b1b79aa381d01303fa81a Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:50 +0000
Subject: [PATCH 126/142] Update source file rdm-methods.md
---
.../reproducible-research/rdm/rdm-methods.md | 33 +++++++++++++++++++
1 file changed, 33 insertions(+)
create mode 100644 book/website/reproducible-research/rdm/rdm-methods.md
diff --git a/book/website/reproducible-research/rdm/rdm-methods.md b/book/website/reproducible-research/rdm/rdm-methods.md
new file mode 100644
index 00000000000..40ee17ac038
--- /dev/null
+++ b/book/website/reproducible-research/rdm/rdm-methods.md
@@ -0,0 +1,33 @@
+(rr-rdm-methods)=
+# Methods and Protocols
+
+This chapter will provide an overview of how to manage your methods or protocols and possibilities for sharing this work with others.
+
+## Why
+
+In order to ensure that others can reproduce your research, it is key that you document all the steps you took during the research process.
+In a wetlab, this is often done in a lab notebook that can be kept on paper or digitally.
+(See the sections on {ref}`Electronic Lab Notebooks (ELNs) ` and {ref}`Open Notebooks ` for more on the latter.)
+In both cases the lab notes should record what you did or observed in the laboratory.
+It should be recording why steps were taken, including mistakes and thoughts or difficulties experienced during data collection and processing.
+You should take notes in a manner that someone else, with a similar research background or yourself in six months, could use your notebook and repeat the work with the same results.
+It is very important to clearly describe every step taken and to be specific, otherwise reusers might misinterpret your documentation which will lead to challenges (as can be seen in this [exact instruction challenge video](https://www.youtube.com/watch?v=cDA3_5982h8)).
+See also the {ref}`Documentation section ` for more information on how to properly document your workflow.
+
+(rr-rdm-methods-open)=
+## Open Methods/Protocols
+
+[protocols.io](https://www.protocols.io/) is a repository for methods.
+You can watch two short introduction videos by [Emma Ganley](https://www.youtube.com/watch?v=hva-oTapSWU&list=PL1CvC6Ez54KCcs99wV3eex1v5GUry6Yb7&index=12) and [Lenny Teytelman](https://www.youtube.com/watch?v=1wN6RqCmpqM&list=PL1CvC6Ez54KDvJbbdLn5rPvf1kInifEh9&index=13) to learn more.
+
+See [methods & protocols - ReproducibiliTeach](https://www.youtube.com/watch?v=CzpY4A5G70s&list=PLWb8IFSVeQ620plPweZIQSGQODpGOww8r&index=3) for the differences between protocol journals and protocol repositories (at 23:33).
+
+You can also choose to [share your electronic lab notes openly](https://www.lornecampbell.org/?p=179).
+
+(rr-rdm-methods-resources)=
+## Additional Resources
+
+* [Course Syllabi for Open and Reproducible Methods](https://osf.io/vkhbt/)
+* [Developing a modern data workflow for evolving data](https://doi.org/10.1101/344804) by {cite:ps}`Yenni2018workflow`
+* [Webinar: How To Perform A Workflow Analysis ](https://www.youtube.com/watch?v=9H9xnVRlc_M)
+
From 7466f84e4e2618e53c576381e2fe385384ddf2cf Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:50 +0000
Subject: [PATCH 127/142] Update source file rdm-personal.md
---
book/website/reproducible-research/rdm/rdm-personal.md | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/book/website/reproducible-research/rdm/rdm-personal.md b/book/website/reproducible-research/rdm/rdm-personal.md
index 6b85b1a3d48..d83704d4694 100644
--- a/book/website/reproducible-research/rdm/rdm-personal.md
+++ b/book/website/reproducible-research/rdm/rdm-personal.md
@@ -3,6 +3,15 @@
For a more practical overview on tools and practises that facilitate reproducibility, please see the [Sensitive Data chapters](https://the-turing-way.netlify.app/project-design/sdp.html) on [managing](https://the-turing-way.netlify.app/project-design/sdpm.html) and [working on](https://the-turing-way.netlify.app/project-design/sdpw.html) sensitive data under the [Guide for Project Design](https://the-turing-way.netlify.app/project-design/project-design.html#pd).
+```{figure} ../../figures/data-ecosystem.*
+---
+name: data-ecosystem-2
+alt: In the illustration the private data is locked up under a well. However, if there is consent, some of the water in this private data well can be shared publicly. Sharing this private data publicly with consent is important for improving public knowledge and scientific progress, which is visualised as a field where people are working on the planting and managing of plants or data charts. The water from the well is used to water the field. The public data that grows thanks to the sharing of the data can then be 'harvested' and be of public benefit.
+
+---
+The private data ecosystem. _The Turing Way_ project illustration by Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807)
+```
+
## Personal data
Personal data is information about **living people** who can be identified using the data that you are processing, either directly or indirectly (for example, a person's name, address or other unique identifier such as their Social Security number).
From 499de5332324962e8dec9a4a2a896e606a7a97c2 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:51 +0000
Subject: [PATCH 128/142] Update source file rdm-repository.md
---
.../rdm/rdm-repository.md | 159 ++++++++++++++++++
1 file changed, 159 insertions(+)
create mode 100644 book/website/reproducible-research/rdm/rdm-repository.md
diff --git a/book/website/reproducible-research/rdm/rdm-repository.md b/book/website/reproducible-research/rdm/rdm-repository.md
new file mode 100644
index 00000000000..eea725892d0
--- /dev/null
+++ b/book/website/reproducible-research/rdm/rdm-repository.md
@@ -0,0 +1,159 @@
+(rr-rdm-repository)=
+# Data Repositories
+
+A repository is a place where digital objects can be stored and shared with others (see also [this repository definition](https://the-turing-way.netlify.app/afterword/glossary.html#term-Repository)).
+
+Data repositories provide access to academic outputs that are reliably accessible to any web user (see the [OpenDOAR inclusion criteria](https://v2.sherpa.ac.uk/opendoar/about.html)).
+Repositories must earn the trust of the communities they intend to serve and demonstrate that they are reliable and capable of appropriately managing the data they hold ({cite:ps}`Lin2020trust`).
+
+Long-term archiving repositories are designed for secure and permanent storage of data, ensuring data preservation over extended periods.
+This differs from platforms like GitHub and GitLab which primarily serve as collaborative development tools, facilitating version control and project management in a more dynamic and transient environment.
+Platforms such as GitHub and GitLab do not assign persistent identifiers to repositories, and their preservation policies are more flexible compared to those of data repositories.
+
+This chapter includes:
+
+- Introduction to repositories
+- An overview of how repositories facilitate you to comply to the FAIR principles
+- How to select an appropriate repository
+- An introduction to the Open Science Framework
+
+(rr-rdm-repository-FAIR)=
+## Repositories and FAIR
+
+Selecting an appropriate repository for your research outputs has many benefits:
+- It helps make your Research Objects more FAIR ({ref}`Findable, Accessible, Interoperable and Reusable`). This is achieved through:
+ - Repositories assign a Persistent Identifier to your Research Objects, which makes them findable and citable (see {ref}`Citing Research Objects`.
+The most commonly used persistent identifiers for research objects is the Digital Object Identifier, usually abbreviated to DOI.
+ - Repositories use metadata standards in describing your Research Object, which ensures that other people can find it using search engines.
+ - Repositories add a licence to the Research Objects.
+A {ref}`license ` describes to potential reusers of your work what they are allowed to do with it.
+ - Repositories provide documentation for Research Objects.
+This can be in the form of READMEs and/or wikis that provide a description of your project and why it might be relevant to people.
+ - Encouraging widely-used file formats.
+Many repositories have restrictions on the file formats used to ensure the sustainability of Research Objects.
+Some file formats (especially proprietary ones with a limited user base) can become deprecated.
+- It allows to determine the levels of access to Research Objects.
+As covered in {ref}`Barriers to Data Sharing`, there are good reasons to not to make all Research Objects completely open.
+However, it's still worthwhile to at least open the metadata and provide an option for people to obtain access to the actual Research Objects if they have certain credentials or if they have been given explicit access.
+That way, your work will still be FAIR (because the metadata are findable and there is an access procedure in place), as well as and secure (because you can control who has access).
+ - Restricting access and storing data on European servers can help to manage sensitive data {ref}`manage sensitive data`
+
+## Why not the supplemental materials?
+
+Supplemental materials are not following the FAIR principles - as there is no seperate DOI assigned to the supplemental materials which makes it difficult to retrieve these materials.
+Next to supplemental materials not being aligned with the FAIR principles, there are other reasons why a data repository is a better solution:
+
+- Data control: Supplementary materials cannot be updated, unlike materials available at data repositories.
+- Interoperability: If publishers only allow text and PDF formats it hampers data sharing and it will be difficult to reuse the data.
+- Availability: Supplementary materials are difficult to access if the article is behind the paywall, and links to supplementary materials can break (since they do not have their own persistent identifier).
+- Impact: Data and code should be a primary research output instead of being hidden in the supplementary materials.
+- Publisher requirements: Some publishers recommend using a data repository instead.
+- Size limits: There may be size limits in place of how large or how many supplementary materials can be shared.
+
+(rr-rdm-repository-select)=
+## Selecting an appropriate repository
+This chapter outlines some of the crucial functionalities that you should look out for when picking where to share your data, code, methods, hardware, slides, or any other Research Object.
+
+Data should be submitted to domain or discipline specific, community recognised, repository where possible.
+A {ref}`general purpose repository` can be used when there are no suitable discipline specific repositories.
+Discipline specific data repositories are likely to have more functionalities for the type of data that you would like to share, as well as community standards that you can adhere to to make the data more FAIR ({ref}`Findable, Accessible, Interoperable and Reusable`). Why sharing data is a good idea is covered in {ref}`Motivations for sharing and archiving data` and {ref}`Open Data`.
+
+The choice of repository can depend on multiple factors:
+
+- Your discipline
+- Type of digital output
+- File size
+- Policies/requirements from institutions, national policies, funding agencies
+- Access restrictions
+
+You can search for relevant repositories on [re3data](https://www.re3data.org/) and [FAIRsharing](https://fairsharing.org/).
+However, a search will likely result in a long list of repositories, which you will need to narrow down.
+The following questions may help you with that:
+
+- Is the data repository discipline-specific and community-recognised? Does it use the recognised standards in my discipline?
+- Is the data repository known by the research community?
+- Are others using the data repository to share their data?
+- Has a data repository been specified by my funder/publisher/institution?
+- What are the file size requirements and limitations?
+- What are the costs for data sharing?
+- What data formats are allowed? Will it take the data that you want to share?
+- Does it provide a persistent identifier, for example a Digital Object Identifier (DOI)?
+- Does it provide the right type of access control that suits the sharing conditions of the data? (restricted access/embargo's)
+- Is there support available on how to curate the data/metadata?
+
+See the [ARDC's Guide to choosing a data repository](https://ardc.edu.au/resource/guide-to-choosing-a-data-repository) or the [DCC checklist for evaluating data repositories](https://www.dcc.ac.uk/guidance/how-guides/where-keep-research-data) for more information.
+
+(rr-rdm-repository-types)=
+## Types of repositories
+
+If your disicpline does not have a disciplinary specific repository you can make use of several general repositories.
+Below follows a (non-exhaustive) list of these different types of repositories:
+
+(rr-rdm-repository-types-general)=
+### General purpose repositories
+
+- [Zenodo](https://zenodo.org/)
+- [Figshare](https://figshare.com/)
+
+### Project repositories
+
+- [Open Science Framework (OSF)](https://osf.io/)
+- [Research Equals](https://www.researchequals.com/)
+- [Octopus](https://www.octopus.ac/)
+- [CRAN](https://cran.r-project.org/) for R-Packages
+
+### Generic data repositories
+
+- [Dryad](https://datadryad.org/stash)
+- [Dataverse](https://dataverse.org/)
+- [4TU.ResearchData](https://data.4tu.nl/)
+- [UK Data Service](https://ukdataservice.ac.uk/)
+
+### Institutional or National repositories
+
+Many countries and/or institutions also provide access to repositories that you could use.
+Check with your local Research Data Management support to see if this available at your institute, or try to search for such a national repository using [re3data](https://www.re3data.org/) and [FAIRsharing](https://fairsharing.org/).
+
+## Recommended Repositories
+
+Several lists of Recommended Repositories by publishers exist:
+
+- [PLOS ONE Recommended Repositories](https://journals.plos.org/plosone/s/recommended-repositories)
+- [Springer Nature Data repository guidance](https://www.springernature.com/gp/authors/research-data-policy/recommended-repositories)
+- [Elsevier's Public repositories to store and find data](https://www.journals.elsevier.com/data-in-brief/policies-and-guidelines/public-repositories-to-store-and-find-data)
+
+(rr-rdm-repository-osf)=
+## Example: Open Science Framework (OSF)
+
+The OSF is a free open-source software project that facilitates open collaboration in science research.
+OSF is way more than a data repository or an archive; it is a collaboration tool which can be used by research teams to work on projects privately or openly, similar to GitHub.
+This case study highlights OSF as one of the repositories *for everything* that you can choose to store your research output long term and make it citable through getting a persistent identifier.
+An example of what you could share on the OSF is a {ref}`research compendium`.
+[Get started with the OSF](https://help.osf.io/article/342-getting-started-on-the-osf) by using the introduction on their website.
+
+### OSF access management
+OSF helps to control levels of access you want to give to different people.
+This can be achieved through OSF folder structure that allows to assign different privacy settings to different folders within one project.
+In OSF terminology, these folders with custom privacy settings are called *components*.
+OSF has servers in Europe which allows compliance with the {ref}`GDPR`.
+
+### OSF and FAIR principles
+The following functionality of OSF helps to make such a folder FAIR ({ref}`Findable, Accessible, Interoperable and Reusable`):
+
+- In addition to its own unique, persistent URLs, OSF offers DOIs for public folders.
+- OSF allows to add metadata to your folder.
+Project metadata fields include at Title, Description, License, Tags and Persistent Identifiers.
+It is possible to add more metadata into the project Wiki or submit in form of a separate file.
+- It is possible to add license to a project to specify how others are allowed to copy, distribute, and make use of this work.
+- OSF provides detailed landing pages to document projects.
+Each *component* has its own wiki that allows to add reach documentation on multiple levels.
+- File formats are not limited by OSF; it is your decision which format to use to make your project future proof.
+
+### Additional OSF resources
+
+- [Introduction to OSF](https://vimeo.com/668636108) by Dr Amy Gillespie
+- [Collaborating, sharing, and preregistering through OSF](https://www.youtube.com/watch?v=48Xy62spsLI) by Anita Eerland.
+
+(rr-rdm-repository-resources)=
+## Additional Repository Resources
+
From 49f924e4ffcc7ac16711f8b5490a2c5cb4d9a2af Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:51 +0000
Subject: [PATCH 129/142] Update source file rdm-resources.md
---
.../rdm/rdm-resources.md | 51 ++++++++++++++++---
1 file changed, 44 insertions(+), 7 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-resources.md b/book/website/reproducible-research/rdm/rdm-resources.md
index bacc3ab8233..0d4ad081064 100644
--- a/book/website/reproducible-research/rdm/rdm-resources.md
+++ b/book/website/reproducible-research/rdm/rdm-resources.md
@@ -11,23 +11,60 @@ If you have not read the chapters on {ref}`rr-open` and {ref}`cm-citable` yet, y
- [Detailed guidance on sharing personal or sensitive data from the UK Data Service](https://www.ukdataservice.ac.uk/manage-data/legal-ethical/consent-data-sharing.aspx)
- [An overview of storage solutions and their advantages and disadvantages](https://web.archive.org/web/20180605213316/http://datasupport.researchdata.nl/en/start-the-course/iii-the-research-phase/storing-data/)
-- {cite:ps}`Henry2021RDM`
-- {cite:ps}`Borer2009RDM`
+- [Reproducible research](https://coderefinery.github.io/reproducible-research/) by Code Refinery
+- [UKRN Open Research Primers](https://www.ukrn.org/primers/)
+- [Eight principles of good data management](https://doi.org/10.31234/osf.io/5tmfe) by {cite:ps}`Henry2021RDM`
+- [Some simple guidelines for effective data management](https://doi.org/10.1890/0012-9623-90.2.205) by {cite:ps}`Borer2009RDM`
+- [Research data management and services](https://doi.org/10.5860/crln.78.5.274) by {cite:ps}`Barbrow2017librarians`
+- [Data Management in Large-Scale Education Research](https://datamgmtinedresearch.com/) by Crystal Lewis
(rr-rdm-resources-resources)=
## Resources
+
+### General
+
+- [The Research Data Management Workbook](https://doi.org/10.7907/z6czh-7zx60)
- [FAIR Cookbook](https://faircookbook.elixir-europe.org/content/home.html)
- [ELIXIR Research Data Management Kit (RDMkit)](https://rdmkit.elixir-europe.org/)
- [Research data management UK data service](https://ukdataservice.ac.uk/learning-hub/research-data-management/)
-- [Webinar: Know Moore About Research Data Management](https://www.youtube.com/watch?v=NCUT6MA-zVA)
-- [Webinar: Introduction to Research Data Management](https://www.youtube.com/watch?v=duDCcV8xhQo)
-- Podcast: Within and Between: [S2E13](https://open.spotify.com/episode/6klHxGUi0v5m5pTFUHbkC4?si=f681d9091fd0490d&nd=1) & [S2E14](https://open.spotify.com/episode/27SXLCsjhtvh4LyfaRIG92?si=9ab8715953584d46&nd=1) on Data Management
-- [Slides on Research Data Management](https://doi.org/10.5281/zenodo.4048591)
-- [Overview of RDM tools](https://rdmkit.elixir-europe.org/index.html)
- [Data resources](https://chanzuckerberg.github.io/open-science/data_sharing/overview)
- [Resources by the Utrecht University Research Data Management support team](https://zenodo.org/communities/uu-rdm-support/)
- [Ten Common Data Management Mistakes](https://cghlewis.com/talk/sssp_ecf/) & [A Curated Collection of Data Management Resources](https://cghlewis.com/blog/data_mgmt_resources/) by Crystal Lewis
- [Data Management for Psychological Science: A Crowdsourced Syllabus](https://docs.google.com/document/d/1z15bL9cP84re6d4zdkO60q06lnknnN3xEktN7GnLFFQ/edit)
+- [ORION Open Science Factsheets](https://www.orion-openscience.eu/publications/training-materials/201808/factsheets)
+- [Reproducible Data Science](https://ecorepsci.github.io/reproducible-science/index.html)
+- [Research Reproducibility and Open Science](https://guides.uflib.ufl.edu/reproducibility/lessons)
+- [PRESENT: research project management](https://www.youtube.com/watch?v=tBGLRXUbCrU&t=524s) by Barbara Vreede
+- [NLM Reproducibility Workshop](https://nlm-repro.github.io/)
+- [A practical guide for transparency in psychological science: Example OSF Project](https://osf.io/xf6ug/)
+- [Software sustainability institute blogpost on training resources](https://www.software.ac.uk/blog/2023-06-20-signpost-training-resources)
+
+### Podcasts
+
+- Podcast: Within and Between: [S2E13](https://open.spotify.com/episode/6klHxGUi0v5m5pTFUHbkC4?si=f681d9091fd0490d&nd=1) & [S2E14](https://open.spotify.com/episode/27SXLCsjhtvh4LyfaRIG92?si=9ab8715953584d46&nd=1) on Data Management
+
+### Presentations/Slides and videos
+
+- [Slides on Research Data Management](https://doi.org/10.5281/zenodo.4048591)
- [Slides: Practicalities of Data Handling](https://doi.org/10.5281/zenodo.5078264)
- [Slides: Research Data Management in the Life Sciences](https://osf.io/mvrny/)
+- [Rethinking Research Data by Kristin Briney ](https://www.youtube.com/watch?v=dXKbkpilQME)
+- [Research Data Management](https://www.youtube.com/watch?v=QRy2uGTpEcQ) by TU Delft Open Science MOOC
+
+### Tools
+
+- [Overview of RDM tools](https://rdmkit.elixir-europe.org/index.html)
+
+### Webinars
+
+- [Webinar: Know Moore About Research Data Management](https://www.youtube.com/watch?v=NCUT6MA-zVA)
+- [Webinar: Introduction to Research Data Management](https://www.youtube.com/watch?v=duDCcV8xhQo)
+- [Webinar: Data sharing and reproducibility by Dr Laurence Hunt](https://vimeo.com/668640629)
+- [Webinar: Publishing and citing data in practice by Jez Cope](https://youtu.be/PpMOkTnBMlI)
+
+# Research Data Management Toolkits
+
+- [JISC research data management toolkit](https://www.jisc.ac.uk/guides/rdm-toolkit)
+- [ELIXIR research data management toolkit](https://rdm.elixir-europe.org/index.html)
+- [University of New Hampshire data management toolkit](https://libraryguides.unh.edu/datamanagement)
From 2bb79a9d53b5e210a850057a73598538ee39d184 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:52 +0000
Subject: [PATCH 130/142] Update source file rdm-sharing.md
---
book/website/reproducible-research/rdm/rdm-sharing.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/book/website/reproducible-research/rdm/rdm-sharing.md b/book/website/reproducible-research/rdm/rdm-sharing.md
index 17402b2d96d..bd6a57f1e29 100644
--- a/book/website/reproducible-research/rdm/rdm-sharing.md
+++ b/book/website/reproducible-research/rdm/rdm-sharing.md
@@ -59,6 +59,7 @@ In many cases, this will include providing data in multiple, standardized format
* The European Commission's [data guidelines](https://open-research-europe.ec.europa.eu/for-authors/data-guidelines)
* Videos on [Data sharing and reuse](https://www.youtube.com/watch?v=4igGBCggU0Y) & [Data Preservation and Archiving](https://www.youtube.com/watch?v=J76yTp8XE-0) from the [TU Delft Open Science MOOC](https://online-learning.tudelft.nl/courses/open-science-sharing-your-research-with-the-world/).
* [Webinar: Why share your data?](https://www.ebi.ac.uk/training/online/courses/bringing-data-life-data-management-biomolecular-sciences/why-share-your-data/)
+* [Webinar: Publishing and citing data in practice by Jez Cope](https://youtu.be/PpMOkTnBMlI)
* Coursera Videos from [Research Data Management and Sharing](https://www.coursera.org/learn/data-management) on the [Benefits of Sharing](https://www.coursera.org/lecture/data-management/benefits-of-sharing-IPZ0h), [Why Archive Data?](https://www.coursera.org/lecture/data-management/why-archive-data-lcQ2m), and [Why is Archiving Data Important?](https://www.coursera.org/lecture/data-management/why-is-archiving-data-important-04Gji)
* [Blog: Ask not what you can do for open data; ask what open data can do for you](http://blogs.nature.com/naturejobs/2017/06/19/ask-not-what-you-can-do-for-open-data-ask-what-open-data-can-do-for-you/)
* {cite:ps}`Levenstein2018sharing`
From 4a50934b4872e84c15f3c6d27ea21c10aeac1264 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:53 +0000
Subject: [PATCH 131/142] Update source file rdm-spreadsheets.md
---
.../rdm/rdm-spreadsheets.md | 49 ++++++++++++++-----
1 file changed, 38 insertions(+), 11 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-spreadsheets.md b/book/website/reproducible-research/rdm/rdm-spreadsheets.md
index 671023dfade..626c5856a46 100644
--- a/book/website/reproducible-research/rdm/rdm-spreadsheets.md
+++ b/book/website/reproducible-research/rdm/rdm-spreadsheets.md
@@ -4,9 +4,9 @@
Spreadsheets, such as Microsoft Excel files, google sheets, and their Open Source alternative [(for instance) LibreOffice](https://www.libreoffice.org), are commonly used to collect, store, manipulate, analyse, and share research data.
Spreadsheets are convenient and easy-to-use tools for organising information into an easy to write and easy to read forms for humans.
However, one should use them with caution, as the use of an inappropriate spreadsheet is a major cause of mistakes in the data analysis workflow.
-There is a collection of [horror-stories](http://www.eusprig.org/horror-stories.htm) that tells how the use of spreadsheets can ruin analysis-based studies due to unexpected behaviour of the spreadsheet or error-prone
-editing processes.
-Some of these mishaps are not unique to spreadsheets, but many, such as [this](https://doi.org/10.1186/s13059-016-1044-7) and [this](https://doi.org/10.1186/1471-2105-5-80), are.
+See for example the [loss of COVID19 data in England due to poor use of Excel](https://www.bbc.com/news/technology-54423988).
+There is a collection of [horror-stories](https://eusprig.org/research-info/horror-stories/) that tells how the use of spreadsheets can ruin analysis-based studies due to unexpected behaviour of the spreadsheet or error-prone editing processes.
+Some of these mishaps are not unique to spreadsheets, but many, such as [Gene name errors](https://doi.org/10.1186/s13059-016-1044-7) (and another [Gene name error example](https://doi.org/10.1186/1471-2105-5-80)), are.
Fortunately, most problems can be avoided with the following recommendations:
- Use spreadsheet in a text-only format (.csv or .tsv),
@@ -28,7 +28,7 @@ While it may help the researchers at some point, one needs to remember that this
As a simple rule, what can be exported in a text-only format, comma-separated values (CSV), or tab-separated values (TSV), can be considered as the data.
Other functions should be avoided when using these programs for research data.
This includes:
-- changing font, color or borders,
+- cell formatting, such as changing font, color or borders,
- using functions,
- merging cells (this one is particularly problematic),
- using specific cell formats (especially dates, see below).
@@ -44,7 +44,7 @@ In addition to the visual feedback, you can now also use this information to fil
(rr-rdm-spreadsheets-format)=
## 2. Tidy Format For Spreadsheets
-If the spreadsheet is poorly organised, then it may be [difficult for collaborators](https://luisdva.github.io/pls-don't-do-this/) to easily {ref}`read-in and re-use ` your data for further analysis.
+If [the spreadsheet is poorly organised](https://luisdva.github.io/pls-don't-do-this/), then it may be difficult for collaborators to easily {ref}`read-in and re-use ` your data for further analysis.
Indeed, a large part of the work of data scientists is to transform the data into a form that the computer can read.
However, this is incredibly time-consuming when the information is split between several spreadsheets and when there are no concrete data transformation plans before the data is acquired.
@@ -89,6 +89,8 @@ If such a taxonomy or ontology is available, using it may allow you (and others)
For example, you may use the generic `male` and `female` term for the sex of an animal (without capitals, and without using abbreviation), as many ontologies use these terms.
Besides, you may want to use some extra tools to validate the spreadsheets before its integration in the analysis.
+(rr-rdm-spreadsheets-missing)=
+### Missing data points
You should also have clear rules about missing data points.
Using `NA`, `NULL`, or empty cells is not trivial and may have different meanings (impossible data point, not recorded, or lost data point).
Imagine a researcher wants to record the time spent before seeing a pollinator land on an iris flower, and no pollinator was seen during the 10-minute experiment.
@@ -105,10 +107,35 @@ In the English versions, a dot is used since the comma has no meaning (`9,000` w
(rr-rdm-spreadsheets-manipulation)=
## 4. Data Manipulation and Analysis
-***Do not manipulate or analyse data in a spreadsheet program.***
+When you manually manipulate data in a spreadsheet program, you will need to record all the steps that you took.
+This can be time consuming and can be avoided by manipulating and analysing the data with automatic analyses or programmes such as [Open Refine](https://openrefine.org/) that will record the data manipulation steps for you.
-In particular, only copy-paste from one spreadsheet to another if the process is used very rarely.
-It is now effortless to read and combine different spreadsheets in the analysis software, with the additional advantage that the software will return an error message if the headers do not fit.
+OpenRefine can be used for tabular data (for example in [social sciences](https://datacarpentry.org/openrefine-socialsci/), [ecology](https://datacarpentry.org/OpenRefine-ecology-lesson/) and [history](https://programminghistorian.org/en/lessons/cleaning-data-with-openrefine).
+OpenRefine can help you to get an overview of large datasets, identify and correct inconsistencies, and integrate datasets.
+It automatically records these processes, saving a script of the steps involved.
+OpenRefine uses your web browser as a graphical interface, but the software runs only locally so it is safe to use for sensitive data.
+
+Automatic manipulation will also help with data validation, as software may return error messages if data is manipulated incorrectly.
+
+(rr-rdm-spreadsheets-validation)=
+## 5. Data validation
+
+- [Excel support page on data validation](https://support.office.com/en-us/article/Apply-data-validation-to-cells-29FECBCC-D1B9-42C1-9D76-EFF3CE5F7249)
+- Check manually whether your data is consistent, complete and correct:
+ - If a column should contain only numeric values or characters, check that there are no non-numeric values or non-character
+ - Check for consistency in names, unit of measurements, data type and so on
+ - Check if there are any empty cells and replace them with your chosen null value (see {ref}`above `)
+ - Remove redundant data (while keeping in mind what could be reused in the future!)
+
+(rr-rdm-spreadsheets-accessibility)=
+## 6. Accessibility
+
+Comma- or Tab-Separated Value (CSV/TSV) formats are not only best for preservation, but for accessibility as well.
+For more information:
+- [Data Curation Primer](https://github.com/DataCurationNetwork/data-primers/blob/master/Accessibility%20Data%20Curation%20Primer/accessibility-data-curation-primer.md#tabular)
+- [Make your Excel documents accessible to people with disabilities](https://support.microsoft.com/en-us/office/make-your-excel-documents-accessible-to-people-with-disabilities-6cc05fc5-1314-48b5-8eb3-683e49b3e593) (Microsoft Office)
+- [Excel Tips](https://accessibility.psu.edu/microsoftoffice/excel/) (Accessibility and Usability at Penn State)
+- [Create Accessible Spreadsheets](https://www.section508.gov/create/spreadsheets/) (General Services Administration of the 49 U.S. - focused on Excel)
(rr-rdm-spreadsheets-tips)=
## Other Tips
@@ -143,7 +170,6 @@ One needs to make sure the information is entered in the column during digitalis
The way you enter the information (that is, the way you design your headers and cell content) may be different depending on the analysis you want to perform.
One should still always try to be as generic and objective as possible and think about any additional analyses one may want to perform.
-
As an example, let us suppose you are interested in depicting if the percentage of flowers whose sepal length is longer than 6 mm is different in three iris species.
You may be inclined to record a true or false column `is-sepal-longer-than-6cm`, but this will restrict the analysis you can perform.
A better solution is to record the length of the sepal (in mm) and automatically create the categorization later.
@@ -179,7 +205,7 @@ One should also use a version history of the spreadsheets (as they will evolve),
Documentation of the spreadsheet, its version history, and the ontologies it is linked to, can be useful for future users.
(rr-rdm-spreadsheets-tips-team)=
-### Working In A Team: Wrap-up
+### Working In A Team
If you are working with a team on data collection, make sure:
- Everyone uses the same software (and software version) to enter the data.
@@ -189,7 +215,6 @@ If you are working with a team on data collection, make sure:
- One person is responsible for answering putative questions during data collection.
- Every spreadsheet is validated before entering the analysis workflow, and as soon as possible.
-
(rr-rdm-spreadsheets-summary)=
## Summary
@@ -204,5 +229,7 @@ If you work in a team, you should take particular care of the conventions and ma
To learn more about data organisation in spreadsheets, you may have a look at the Data Carpentry lessons for [Social Scientists](https://datacarpentry.org/spreadsheets-socialsci/) and [Ecologists](https://datacarpentry.org/spreadsheet-ecology-lesson/).
+To read about recommended practices, see {cite:ps}`Broman2018data`
+
See also a blogpost with [resources for using spreadsheets in research and moving onto other tools](https://www.software.ac.uk/blog/2021-11-05-resources-using-spreadsheets-research-and-moving-other-tools).
From c3f9963a6e3a46ff213be40a8308087abb049f05 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:53 +0000
Subject: [PATCH 132/142] Update source file rdm-storage.md
---
.../website/reproducible-research/rdm/rdm-storage.md | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/book/website/reproducible-research/rdm/rdm-storage.md b/book/website/reproducible-research/rdm/rdm-storage.md
index f87bf3160bc..675b771cf90 100644
--- a/book/website/reproducible-research/rdm/rdm-storage.md
+++ b/book/website/reproducible-research/rdm/rdm-storage.md
@@ -48,6 +48,7 @@ _The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licen
- Make sure you have enough (sub)folders so that files can be stored in the right folder and are not scattered in folders where they do not belong, or stored in large quantities in a single folder.
- Use a clear folder structure.
You can structure folders based on the person that has generated the data/folder, chronologically (month, year, sessions), per project (as done in the example below), or based on analysis method/equipment or data type.
+- Avoid overlapping or vague folder names, and do not use personal data in folder/file names.
(rr-rdm-storage-organisation-examples)=
### Data Organisation Examples
@@ -77,6 +78,7 @@ Some other tips for file naming include:
- Use the version number of file (v001, v002) or language used in the document (ENG)
- Do not make file names too long (this can complicate file transfers)
- Avoid special characters (?\!@\*%{[<>) and spaces
+- Avoid personal data in file names
You can explain the file naming convention in a README.txt file so that it will also become apparent to others what the file names mean.
@@ -92,9 +94,9 @@ If you want to change your file names you have the option to use bulk renaming t
Be careful with these tools, because changes made with bulk renaming tools may be too rigorous if not carefully checked!
Some bulk file renaming tools include:
-- [Bulk Rename Utility](http://www.bulkrenameutility.co.uk/Main_Intro.php) and [WildRename](http://www.cylog.org/utilities/wildrename.jsp) (for Windows)
+- [Bulk Rename Utility](http://www.bulkrenameutility.co.uk/Main_Intro.php), [WildRename](http://www.cylog.org/utilities/wildrename.jsp), and [Ant Renamer](http://www.antp.be/software/renamer) (for Windows)
- [Renamer](https://renamer.com/) (for MacOS)
-- [PSRenamer](http://www.cylog.org/utilities/wildrename.jsp)(for MacOS, Windows, Unix, Linux)
+- [PSRenamer](http://www.cylog.org/utilities/wildrename.jsp) (for MacOS, Windows, Unix, Linux)
(rr-rdm-storage-backups)=
## Backups
@@ -108,7 +110,9 @@ To avoid losing your data, you should follow good backup practices.
Backups are ideally done automatically and should take into consideration your institute's guidelines.
The more important the data and the more often the datasets change, the more frequently you should back them up.
If your files take up a large amount of space and backing up all of them proves to be challenging or expensive, you may want to create a set of criteria for when you back up the data.
-This can be part of your data management plan (DMP).
-
+This can be part of your {ref}`Data Management Plan`.
Watch this video on [Safe data storage and backup](https://www.youtube.com/watch?v=bgbbToXHgW0) from the [TU Delft Open Science MOOC](https://online-learning.tudelft.nl/courses/open-science-sharing-your-research-with-the-world/).
+
+
+
From d5a6784c9f5e89356eec40ecbff5a4dbabd84f28 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:54 +0000
Subject: [PATCH 133/142] Update source file rdm-visualisation.md
---
.../rdm/rdm-visualisation.md | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 book/website/reproducible-research/rdm/rdm-visualisation.md
diff --git a/book/website/reproducible-research/rdm/rdm-visualisation.md b/book/website/reproducible-research/rdm/rdm-visualisation.md
new file mode 100644
index 00000000000..255a560132f
--- /dev/null
+++ b/book/website/reproducible-research/rdm/rdm-visualisation.md
@@ -0,0 +1,89 @@
+(rr-rdm-visualisation)=
+# Data Visualisation
+
+Data visualisation allows you to:
+* Extract valuable information and patterns from data
+* Communicate this in a clear and comprehensible visual representation
+* Enhance the communication of research findings, making it accessible to a broader audience
+* Identify data quality issues, as outliers and data errors may become more visible in visualisations
+
+Therefore, data visualisation is an aspect of research data management!
+
+Below follow some resources that may help you in creating clearer, more accessible and more transparant data visualisations.
+
+
+
+(rr-rdm-visualisation-tools)=
+## Tools
+
+- [Datawrapper](https://www.datawrapper.de/), where you can upload your data to generate tables and charts.
+- [upset graphs](https://upset.app/) are a straightforward way to visualize set intersections in a matrix layout, which can help in analysing multiple datasets at once.
+- Using **Python Plotly** you can add annotations and animations as extra visual cues to highlight important features.
+ - [Annotating visualisations in Python plotly](https://medium.com/nerd-for-tech/enriching-data-visualizations-with-annotations-in-plotly-using-python-6127ff6e0f80) (blog and video)
+ - [Animations using Python plotly](https://youtu.be/kMFvpmOaF2I)
+
+(rr-rdm-visualisation-accessibility)=
+## Accessibility
+
+- [Tips to improve interpretability and accessibility](https://www.youtube.com/watch?v=RzT95DVUMnw) by Dr Tracey Weissgerber (video)
+- [Writing Meaningful Alt-Texts for Data Visualisations in R](https://www.youtube.com/watch?v=dXV5bx1WQTM)
+- [Writing Alt Text to communicate the meaning in data visualizations] by {cite:ps}`Hare2022dataviz`
+- [Alt-texts](https://axesslab.com/alt-texts/)
+
+(rr-rdm-visualisation-colours)=
+## Colours
+- [A detailed guide to colors in data vis style guides](https://blog.datawrapper.de/colors-for-data-vis-style-guides/) (blog)
+
+(rr-rdm-visualisation-resources)=
+## Resources
+
+### Books and Articles
+
+- [Fundamentals of Data Visualisation](https://serialmentor.com/dataviz/) by {cite:ps}`Wilke2019dataviz`
+- [Data Visualisation, A practical introduction](https://socviz.co/) by {cite:ps}`Healy2018dataviz`
+- [Creating clear and informative image-based figures for scientific publications](https://doi.org/10.1371/journal.pbio.3001161) by {cite:ps}`Jambor2021dataviz`
+- [A layered grammar of graphics](http://dx.doi.org/10.1198/jcgs.2009.07098) by {cite:ps}`Wickham2010dataviz`
+- A Field Guide to Digital Color by {cite:ps}`Stone2003dataviz`
+- The Grammar of Graphics by {cite:ps}`Wilkinson1999dataviz`
+- The Visual Display of Quantitative Information by {cite:ps}`Tufte2001dataviz`
+
+
+### Other text resources and examples
+
+- [Data Visualisation Course](https://exploratory-data-visualization.netlify.app/)
+- [Free visual and communication resources](https://padlet.com/evansemporiumstore/lks3aoyyhkpnkmpe)
+- [A collection of notebooks demonstrating plotting with matplotlib](https://github.com/KirstieJane/NH19-Visualization/)
+- [A Comprehensive Guide to the Grammar of Graphics for Effective Visualization of Multi-dimensional Data](https://towardsdatascience.com/a-comprehensive-guide-to-the-grammar-of-graphics-for-effective-visualization-of-multi-dimensional-1f92b4ed4149)
+- [Friends Don't let Friends Write Bad Graphs](https://github.com/cxli233/FriendsDontLetFriends) by {cite:ps}`li2023dataviz`
+
+### Videos
+
+- 5 minute videos on [Data visualisation - Introduction and motivation](https://www.youtube.com/watch?v=7t2qYO2zEWQ) and [Figure design, design process, fundamentals](https://www.youtube.com/watch?v=WtYArH4EIRg)
+- [Create Effective Data Visualizations](https://youtu.be/jt-VdyFzjj0) (second part focuses primarily on Tableau)
+- [Data visualisation for scientific papers](https://www.youtube.com/playlist?list=PLWb8IFSVeQ62NbG-u4vQlh4srFcC2KH5g) videos by ReproducibiliTeach
+- Outline of grammar of graphics
+ - [A Grammar of Graphics](https://www.youtube.com/watch?v=RCaFBJWXfZc) - Excellent summary of the grammar of graphics layers or 'functional pipeline'
+ - [Leland Wilkinson - The Grammar of Graphics](https://www.youtube.com/watch?v=1X93Sum_SyM) - Leland himself giving a quick high level summary of the grammar of graphics
+- [Martin Krzywinski: A pandemic of bad charts](https://www.youtube.com/watch?v=_YGmfsKL8N8)
+- [EMBL Keynote Lecture 2019 - Data visualization and data science, Hadley Wickham](https://www.youtube.com/watch?v=9YTNYT1maa4)
+- Practical high level intros to Tufte's principles
+ - [What should we do to improve our graphics and figures?](https://www.youtube.com/watch?v=00Fha1lkRxk)
+ - [Graphical Excellence](https://www.youtube.com/watch?v=VkyzSAPkQ50)
+
+### Podcasts
+
+- [Data Viz Today](https://dataviztoday.com/)
+- [Data Stories](https://datastori.es/)
+- [PolicyViz](https://policyviz.com/podcast/)
+
+### Other
+
+- [biovis](http://biovis.net/)
From c469c0442ed8279fa4239c33bfe6be161ac4aa07 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:54 +0000
Subject: [PATCH 134/142] Update source file renv.md
---
book/website/reproducible-research/renv.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/reproducible-research/renv.md b/book/website/reproducible-research/renv.md
index e2f962c55da..8378951d7e6 100644
--- a/book/website/reproducible-research/renv.md
+++ b/book/website/reproducible-research/renv.md
@@ -6,8 +6,8 @@
| Prerequisite | Importance | Notes |
| ------------ | ---------- | ------ |
-| [Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Necessary | Experience with downloading software via the command line is particularly useful |
-| {ref}`rr-vcs` | Helpful | Experience using git and GitHub are helpful |
+| {ref}`Experience with the command line` | Necessary | Experience with downloading software via the command line is particularly useful |
+| {ref}`Version Control` | Helpful | Experience using git and GitHub are helpful |
**Recommended Skill Level**: _Intermediate-Advanced_
From fbd676ba67ff4bfbb79f12914783b95d23e28cd1 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:57 +0000
Subject: [PATCH 135/142] Update source file reviewing-checklist.md
---
.../reproducible-research/reviewing/reviewing-checklist.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/book/website/reproducible-research/reviewing/reviewing-checklist.md b/book/website/reproducible-research/reviewing/reviewing-checklist.md
index 57d641de450..27ec14cce08 100644
--- a/book/website/reproducible-research/reviewing/reviewing-checklist.md
+++ b/book/website/reproducible-research/reviewing/reviewing-checklist.md
@@ -35,8 +35,8 @@ In all cases, the goal is to use your programming experience to figure out how t
The essential architectural concepts can be reviewed as follows:
- Check the [interfaces](#interfaces) lists.
- Check the [classes and types](#classes-and-types) lists.
- - Check the [function/method declarations](#function-method-declarations) lists.
- - Check the [function/method definitions](#function-method-definitions) lists.
+ - Check the [function/method declarations](#functionmethod-declarations) lists.
+ - Check the [function/method definitions](#functionmethod-definitions) lists.
- Do the [tests](#tests) actually ensure the code is robust in its intended use?
- Are there any bugs or other defects?
- Are [security](#security) issues handled correctly?
From 4530ae80c06214a2492dc8a86f6dde044b03be15 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:35:59 +0000
Subject: [PATCH 136/142] Update source file testing.md
---
book/website/reproducible-research/testing.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/testing.md b/book/website/reproducible-research/testing.md
index de82016a56a..dcc715966eb 100644
--- a/book/website/reproducible-research/testing.md
+++ b/book/website/reproducible-research/testing.md
@@ -3,7 +3,7 @@
| Prerequisite | Importance |
| -------------|------------|
-| [Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Necessary |
+| {ref}`Experience with the command line` | Necessary |
## Summary
From b41219d21afbebf1ae3ea03238c10b795a8fa03c Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:01 +0000
Subject: [PATCH 137/142] Update source file testing-guidance.md
---
book/website/reproducible-research/testing/testing-guidance.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/book/website/reproducible-research/testing/testing-guidance.md b/book/website/reproducible-research/testing/testing-guidance.md
index a8c2e9198b7..01d75c2e80e 100644
--- a/book/website/reproducible-research/testing/testing-guidance.md
+++ b/book/website/reproducible-research/testing/testing-guidance.md
@@ -106,6 +106,7 @@ In general, the best tests are those that isolate the smaller rather than larger
Try to be guided by thinking about the possible things that might happen to a particular chunk of code in the execution of the whole, and test these individual cases.
Often, this will result in the same code being tested multiple times - this is a good thing!
+(rr-testing-guidance-mocking)=
## Use test doubles/stubs/mocking where appropriate
If a test fails it should be constructed such that it is as easy to trace the source of the failure as possible.
From 2701925cfeea831d2f8a3a7e0cea95ac12adb625 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:01 +0000
Subject: [PATCH 138/142] Update source file testing-integrationtest.md
---
.../reproducible-research/testing/testing-integrationtest.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/testing/testing-integrationtest.md b/book/website/reproducible-research/testing/testing-integrationtest.md
index dc468ff9482..99108f3d7da 100644
--- a/book/website/reproducible-research/testing/testing-integrationtest.md
+++ b/book/website/reproducible-research/testing/testing-integrationtest.md
@@ -55,7 +55,7 @@ So is a code can be split into the main steps A, B, and C, and each of those con
So in the top down approach the integration between sections at the top level (A, B and C) are tested, then integration between sections at the next level (for example, A.1 -> A.2) and so on.
Testing upper level units by running all the code they contain including running lower level ones can lead to upper level tests breaking due to bugs in low level units.
-This is undesirable, so to prevent this the lower level sections should not be run, but [test stubs](#Use_test_doubles_stubs_mocking_where_appropriate) should be used to simulate the outputs from them.
+This is undesirable, so to prevent this the lower level sections should not be run, but [test stubs][rr-testing-guidance-mocking] should be used to simulate the outputs from them.
Bottom Up is an approach to integration testing where integration between bottom level sections are tested first and upper-level sections step by step after that.
Again test stubs should be used, in this case to simulate inputs from higher level sections.
From 20c32091319b0f7be9d31769fd6a582417dfe515 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:02 +0000
Subject: [PATCH 139/142] Update source file testing-overview.md
---
.../reproducible-research/testing/testing-overview.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/book/website/reproducible-research/testing/testing-overview.md b/book/website/reproducible-research/testing/testing-overview.md
index 7c62e4b6ce3..2bb3c544617 100644
--- a/book/website/reproducible-research/testing/testing-overview.md
+++ b/book/website/reproducible-research/testing/testing-overview.md
@@ -15,18 +15,18 @@ A thorough test suite will contain tests at all of these levels (though some lev
(rr-testing-types-of-testing)=
## Types of Testing
-[Smoke testing](#Smoke_testing): Very brief initial checks that ensures the basic requirements required to run the project hold.
+[][rr-testing-smoketest]: Very brief initial checks that ensures the basic requirements required to run the project hold.
If these fail there is no point proceeding to additional levels of testing until they are fixed.
-[Unit testing](#Unit_tests): A level of the software testing process where individual units of a software are tested. The purpose is to validate that each unit of the software performs as designed.
+[][rr-testing-unittest]: A level of the software testing process where individual units of a software are tested. The purpose is to validate that each unit of the software performs as designed.
-[Integration testing](#Integration_testing): A level of software testing where individual units are combined and tested as a group.
+[][rr-testing-types-integrationtest]: A level of software testing where individual units are combined and tested as a group.
The purpose of this level of testing is to expose faults in the interaction between integrated units.
-[System testing](#System_tests): A level of the software testing process where a complete, integrated system is tested.
+[][rr-testing-systemtest]: A level of the software testing process where a complete, integrated system is tested.
The purpose of this test is to evaluate whether the system as a whole gives the correct outputs for given inputs.
-[Acceptance testing](#Acceptance_testing): A level of the software testing process where a system is tested for acceptability.
+[][rr-testing-acceptance-regression]: A level of the software testing process where a system is tested for acceptability.
The purpose of this test is to evaluate the system's compliance with the project requirements and assess whether it is acceptable for the purpose.
Here's an analogy: during the process of manufacturing a ballpoint pen, the cap, the body, the tail, the ink cartridge and the ballpoint are produced separately and unit tested separately.
From 77869ff0bb40fab35874a64bd09b483dd8358d31 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:03 +0000
Subject: [PATCH 140/142] Update source file testing-unittest.md
---
book/website/reproducible-research/testing/testing-unittest.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/testing/testing-unittest.md b/book/website/reproducible-research/testing/testing-unittest.md
index 5ec849e9458..7873b2cbef7 100644
--- a/book/website/reproducible-research/testing/testing-unittest.md
+++ b/book/website/reproducible-research/testing/testing-unittest.md
@@ -71,7 +71,7 @@ In contrast, if the code that does this Useful Thing is entwined with a great de
- Many testing frameworks have tools specifically geared towards writing and running unit tests.
- Isolate the development environment from the test environment.
-- Write test cases that are independent of each other. For example, if a unit A utilises the result supplied by another unit B, you should test unit A with a [test double](#Use_test_doubles_stubs_mocking_where_appropriate), rather than actually calling the unit B. If you don't do this your test failing may be due to a fault in either unit A *or* unit B, making the bug harder to trace.
+- Write test cases that are independent of each other. For example, if a unit A utilises the result supplied by another unit B, you should test unit A with a [test double][rr-testing-guidance-mocking], rather than actually calling the unit B. If you don't do this your test failing may be due to a fault in either unit A *or* unit B, making the bug harder to trace.
- Aim at covering all paths through a unit. Pay particular attention to loop conditions.
- In addition to writing cases to verify the behaviour, write cases to ensure the performance of the code. For example, if a function that is supposed to add two numbers takes several minutes to run there is likely a problem.
- If you find a defect in your code write a test that exposes it. Why? First, you will later be able to catch the defect if you do not fix it properly. Second, your test suite is now more comprehensive. Third, you will most probably be too lazy to write the test after you have already fixed the defect. Say a code has a simple function to classify people as either adults or children:
From 3b56bc7c7da7748bf93865bfe9613bf2e02fa106 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:04 +0000
Subject: [PATCH 141/142] Update source file vcs.md
---
book/website/reproducible-research/vcs.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/book/website/reproducible-research/vcs.md b/book/website/reproducible-research/vcs.md
index 777345fe80d..51e47e93c57 100644
--- a/book/website/reproducible-research/vcs.md
+++ b/book/website/reproducible-research/vcs.md
@@ -6,7 +6,7 @@
| Prerequisite | Importance | Notes |
| -------------|----------|------|
-|[Experience with the command line](https://programminghistorian.org/en/lessons/intro-to-bash) | Helpful | |
+| {ref}`Experience with the command line` | Helpful | |
**Recommended Skill Level**: _Beginner-Intermediate_
From 16587eac42588cf79548d691ae65d6fb921adf47 Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <53487593+BatoolMM@users.noreply.github.com>
Date: Sat, 24 Feb 2024 19:36:09 +0000
Subject: [PATCH 142/142] Update source file _toc.yml
---
book/website/_toc.yml | 65 ++++++++++++++++++++++++++++++++++---------
1 file changed, 52 insertions(+), 13 deletions(-)
diff --git a/book/website/_toc.yml b/book/website/_toc.yml
index 7edb73773d7..1124fd9080f 100755
--- a/book/website/_toc.yml
+++ b/book/website/_toc.yml
@@ -84,8 +84,10 @@ parts:
- title: Licensing
file: reproducible-research/licensing
sections:
- - title: Software Licenses
- file: reproducible-research/licensing/licensing-software
+ - title: License Compatibililty
+ file: reproducible-research/licensing/licensing-compatibility
+ - title: Ethics-informed Licensing
+ file: reproducible-research/licensing/licensing-ethical-source
- title: Data Licenses
file: reproducible-research/licensing/licensing-data
- title: Hardware Licenses
@@ -95,8 +97,7 @@ parts:
sections:
- title: "Case Studies: Choosing an ML License"
file: reproducible-research/licensing/licensing-ml-case-studies
- - title: License Compatibililty
- file: reproducible-research/licensing/licensing-compatibility
+
- title: Checklist
file: reproducible-research/licensing/licensing-checklist
- title: Research Data Management
@@ -104,6 +105,8 @@ parts:
sections:
- title: Research Data
file: reproducible-research/rdm/rdm-data
+ - title: Finding Data
+ file: reproducible-research/rdm/rdm-find
- title: Data Management Plan
file: reproducible-research/rdm/rdm-dmp
- title: The FAIR Principles and Practices
@@ -116,18 +119,24 @@ parts:
file: reproducible-research/rdm/rdm-spreadsheets
- title: Documentation and Metadata
file: reproducible-research/rdm/rdm-metadata
+ - title: Methods and Protocols
+ file: reproducible-research/rdm/rdm-methods
+ - title: Electronic Lab Notebooks (ELNs)
+ file: reproducible-research/rdm/rdm-elns
- title: Data Curation
file: reproducible-research/rdm/rdm-data-curation
+ - title: Data Visualisation
+ file: reproducible-research/rdm/rdm-visualisation
+ - title: Data Repositories
+ file: reproducible-research/rdm/rdm-repository
- title: Sharing and Archiving Data
file: reproducible-research/rdm/rdm-sharing
- title: Data Article
file: reproducible-research/rdm/rdm-article
- - title: Research Data Management Toolkits
- file: reproducible-research/rdm/rdm-toolkits
- - title: Personal Impact Stories
- file: reproducible-research/rdm/rdm-stories
- title: Checklist
file: reproducible-research/rdm/rdm-checklist
+ - title: Personal Impact Stories
+ file: reproducible-research/rdm/rdm-stories
- title: Resources
file: reproducible-research/rdm/rdm-resources
- title: Reproducible Environments
@@ -265,7 +274,7 @@ parts:
sections:
- title: Planning for Project Design
file: project-design/pd-overview/pd-overview-planning
- - title: Communication and Collaboration
+ - title: Collaborative project documentation
file: project-design/pd-overview/pd-overview-repro
- title: Reproducibility Methods
file: project-design/pd-overview/pd-overview-methods
@@ -273,6 +282,8 @@ parts:
file: project-design/pd-overview/pd-overview-version
- title: Sharing Your Research Work
file: project-design/pd-overview/pd-overview-sharing
+ - title: Project Design Checklist
+ file: project-design/pd-checklist
- title: Creating Project Repositories
file: project-design/project-repo
sections:
@@ -352,6 +363,8 @@ parts:
sections:
- title: Data Governance for the Machine Learning Pipeline
file: project-design/data-governance/data-gov-ml
+ - title: BigCode Data Governance Case Study
+ file: project-design/data-governance/bigcode_casestudy
# ===== Guide for Communication ========================================
@@ -398,9 +411,9 @@ parts:
- title: Social Media for Research Communications
file: communication/social-media
sections:
- - title: Tips for starting with twitter
+ - title: Tips for starting with X
file: communication/social-media/social-media-twitter-tips
- - title: Managing multiple twitter accounts
+ - title: Managing multiple X accounts
file: communication/social-media/social-media-twitter-multiple
- title: Research Objects in Action
file: communication/research-objects
@@ -555,6 +568,9 @@ parts:
file: collaboration/academic-industry/academic-industry-personal-story
- title: Team Manual
file: collaboration/team-manual
+ sections:
+ - title: On and Offboarding Team Members
+ file: collaboration/team-manual/team-manual-on-off-boarding
- title: Open Leadership in Data Science
file: collaboration/leadership
sections:
@@ -642,6 +658,8 @@ parts:
file: ethical-research/law-policy/law-policy-resources
- title: Research Ethics for Social Data
file: ethical-research/social-data
+ - title: Data Feminism
+ file: ethical-research/data-feminism
- title: Activism for Researchers
file: ethical-research/activism
sections:
@@ -668,9 +686,19 @@ parts:
file: ethical-research/self-reflection/sr-prompts
- title: Resources
file: ethical-research/self-reflection/sr-resources
+ - title: Data-Hazards
+ file: ethical-research/data-hazards
+ sections:
+ - title: Introduction
+ file: ethical-research/data-hazards/dh-intro
+ - title: How To Use
+ file: ethical-research/data-hazards/dh-how-to-use
+ - title: Case Study
+ file: ethical-research/data-hazards/dh-case-study
- title: Ethical Considerations for Open Source Governance Models
file: ethical-research/ethics-open-source-governance
+
# ===== Community Handbook ========================================
- file: community-handbook/community-handbook
@@ -744,6 +772,13 @@ parts:
file: community-handbook/infrastructure/infrastructure-contributors
- title: External Link Checking
file: community-handbook/infrastructure/infrastructure-external-link-check
+ - title: Communication Platforms
+ file: community-handbook/communication-channels
+ sections:
+ - title: Slack Start Guide
+ file: community-handbook/communication-channels/slack-start-guide
+ - title: Slack Welcome Guide
+ file: community-handbook/communication-channels/slack-welcome-guide
- title: Monthly Newsletters
file: community-handbook/newsletters
sections:
@@ -816,9 +851,13 @@ parts:
sections:
- title: Legal Disclaimer
file: afterword/legal-disclaimer
+ - title: Contributors Record
+ file: afterword/contributors-record
+ - title: Collaborators
+ file: afterword/collaborators
+ - title: Sub-projects, Working Groups, Informal Initiatives
+ file: afterword/subprojects
- title: Glossary
file: afterword/glossary
- title: Bibliography
file: afterword/bibliography
- - title: Contributors Record
- file: afterword/contributors-record