Photo by Prateek Katyal on Unsplash

If you have any questions, please contact Shoaib Sufi (shoaib.sufi@software.ac.uk)

Why WoH22

Handbooks (sometimes called toolkits or knowledgebases) are a mechanism for knowledge collection, management and distribution. Constructing and maintaining them aids in the capture and promotion of best practice and forms a useful reference for beginners and experts alike in a given domain or area of skill.

Handbooks are a hot topic; a number of different projects and individuals are currently growing and nurturing handbooks in areas relevant to the research software community. 

WoH22 is a platform for sharing experiences, discussing best practices and formulating advice for others who are considering or at the early stages of handbook development.

Who should attend

If you are building a handbook of relevance to the Research Software community or are starting out on the journey then you will get the opportunity to hear about similar projects, discuss and formulate advice with others and get ahead on how to build and nurture your handbook.

What do we mean by 'handbook'

By handbook, we mean guides that address a set of specific roles (e.g. researcher, manager) in their efforts to better perform a research or research-related activity (e.g reproducibility, data management, research event management). Handbooks highlight tools and guidance to help them achieve their goals, help their productivity and that of their collaborators. Examples of handbooks which we may have come across are Wikis and guides that labs put together, sets of necessary, common and best practices that often help onboard people and act as a reference for the group. The handbooks we focus on in WoH22 are more public facing and help address a facet or are of relevance to the research software community in a broad sense.

What’s in a Handbook

Handbooks can include materials in a variety of forms that cover:

• Motivation 
  • Why the activity and advice is important and timely
  • What motivated the contributors to formulate the advice
• Know-how
• How-to’s / recipes
• Tools
• Examples and templates
• Best practice
• Guides on how to manage specific challenges in an activity
• Aids to compliance (e.g. with funder, regulatory or community requirements)
• Case studies and personas
• Novel navigational aids to the handbook (e.g. accessibility wheels)
• Information on how to reuse material and incorporate it in your guidance

Examples of Handbooks

Many Handbooks aim to be a single reference point for a particular activity or set of related activities and thereby become a trusted source of comprehensive and easy to follow advice that allows those using it to reach their goals, save time and have confidence that they have referred to experts.

Examples of Handbooks include:

• Software
  • The Turing Way - an open source community-driven guide to reproducible, ethical, inclusive and collaborative data science - https://the-turing-way.netlify.app/welcome.html 
  • UX Toolkit for Life Sciences  - to enable businesses to adopt UX principles and methods as they develop scientific software - https://uxls.org/ 
  • rOpenSci Packages - a guide for creating, testing, reviewing and nurturing Open Science compliant R packages - https://devguide.ropensci.org/ 
• Data
  • ELIXIR RDMKit - The ELIXIR Research Data Management Kit (RDMkit) is an online guide containing good data management practices applicable to research projects from the beginning to the end - https://rdmkit.elixir-europe.org/ 
  • FAIR Cookbook - Aims to collate protocols for making data FAIR and provide examples of dataset FAIRification relevant to the Innovative Medicines Initiative (IMI) - https://fairplus.github.io/the-fair-cookbook 
• Training
  • Carpentries Curriculum Development Handbook - a guide for creating curricula that adheres to the Carpentries initiative ethos - https://cdh.carpentries.org/index.html 
• Project management:
  • SSI Event Organisation Guide - A guide about organising events structured in the way the Software Sustainability Institute does event organisation - https://event-organisation-guide.readthedocs.io/ 

What is not included in the definition of a Handbook

We are not counting a resource which is a set of training lessons as a Handbook. Handbooks have active and cohesive curation as well as a focus on guiding people around resources. In this sense Programming Historian and The Carpentries lessons (as brilliant as they are) don’t constitute a Handbook; if they had additional guidance around the resource and how they sit together - that would be a Handbook.

Event roles

Event Lead (SSI) - Shoaib Sufi

Senior stakeholder (SSI) - Neil Chue Hong

Steering group:

• Toby Hodges (Capentries Curriculum Development Handbook)
• Malvika Sharan (Turing Way)
• Munazah Andrabi (ELIXIR RDMKit)
• Daniele Procida (Diátaxis Framework)
• Shoaib Sufi (Event Lead & SSI Event Organisation Guide)