very-good-science / our-handbook-user-guide Goto Github PK

• How to fork/use template
• How to update handbook from recent changes to template (sync changes)
• How to add back in sections to the our-handbook-template repository

✨ This checklist contains our priorities for the E-life innovation sprint ✨

We have the following aims for the sprint:

• To create two new sections of the template handbook, e.g. “working on side projects”, “getting the most out of one-to-ones”, or “writing a preregistration”. These might be sections that we’ve already identified or ideas that the participants come with.
  • Section 1
• An example handbook using the template repository: so that we can show potential users what the end goal is for them. E.g. “The Jean Golding Institute’s Data Science handbook”.
• More detailed instructions for how to use the template repository.
• More detailed contribution guidelines for future contributors, who fit the user profile “I’ve never used GitHub before, but have this resource that I use with my group, how can I add it in?”.

• GitHub
  • Labels (to match template labels)
  • Issues + milestone checklist linking
  • GH Actions (deploying book)
  • all-contributors
• Jupyter book
  • Basic setup

• Contact The Turing Way: https://github.com/alan-turing-institute/the-turing-way
• Contact The RSE Toolkit: https://github.com/RSEToolkit/RSEToolkit.github.io
• Contact Wellcome re: their research culture town hall report
• Apply for SSI Collaboration Workshop 2021: deadline 31/01/21
  • Create applications/talks section on GitHub (draft in comments for now)

Basic Setup

• GitHub + Jupyter book setup (#8)

Sections

• Welcome
  • Tour of materials (template + metahandbook, deployed + github versions)
• How to use the template
  • Quickstart guide
  • Getting started
  • Preparing for an away day
    • Template schedule (maybe a 1 and a 2 day version) to send out to attendees
      • DAY 1:
        • photo shoot (group/individual photos)
        • tour of the book + the repo (contributing guidelines/code of conduct)
        • look at examples for inspiration
        • brainstorm sections for your book that aren't already on the list
        • delete sections/add new sections from existing list
        • prioritise new list of sections
        • split up sections (sometimes individual/sometimes pairs/sometimes the whole group) - make note in a GitHub issue/checklist.
        • free-writing
        • write content for a joint section together, following one of the writing exercises
        • split up to write on your own/in pairs/in groups
        • leave plenty of time for merging pull requests
        • Put your book online
      • DAY 2
        • free-writing
        • jointly write content with writing exercise
        • individual/pair/small group editing + writing
        • merging pull requests
        • new version online
        • ensure that you have maintainers locked down
        • make a plan for any further edits (when by/who, and when to review together - group meeting?)
    • A GitHub savvy person should volunteer to manage the repository - link to training materials.
      • Make the issue labels and a Milestone
      • Make sure everyone has GitHub accounts and add them as collaborators
      • Maybe hold a GitHub intro/training session in advance of the main handbook day if you need to
      • Make sure everyone has a good text editor with a working terminal
      • Delete Our Handbook contributors
      • (Optional) Edit/add issue templates
  • Editing the template
    • Lead handbook-er
      • Remove the sections from the TOC for things that you are going to do. Remove markdown for things that you aren't going to do.
    • Basics (everyone needs to know)
      • Jupyter book syntax
      • Template specifics (FIXMEs, comments, options, writing exercises)
      • How to edit (GitHub flow: Make an issue, comment on the issue, fork the repo, make a WIP PR, edit, preview/local serve, commit, ask for review/make PR "ready to review", merge PR).
      • Advice for editing
        • Don't work on the same bits all at once, if you want to avoid merge conflicts.
        • VS code > Pycharm for jupyter book syntax
  • Deploying your handbook online
  • Actioning your roadmap, embodying your values, etc
• Maintaining the handbook
  • On-boarding a new team member
  • Review as a team
  • Review in one-to-ones
• Contributing to the project
  • Contributing to the template
  • Contributing to the handbook

Extremely optional section!

• Logo
• CSS/styles

Some of the links on the readme direct to 404 page not found. We need to read through and make sure that the links work and are correct, and also make sure that the readme itself has up to date instructions.

Bristol Suggestions:

• JGI Data Scientists
• Oliver Davies
• Al's Physics group
• Marcus Munafo
• CARQI fellows
• RSE Group (could fit in with RSEToolkit)

The JGI Data Scientists Handbook will be the first research group handbook deployed using the Our Handbook template. To create it, I will:

• Follow the instructions in the Our Handbook handbook
  • Fork the template to the Jean Golding Institute Organisation
  • Organise an away day where we edit/add important links.

After the prototype of the handbook template is created, it would be nice to have video explanations of how to use the handbook.

This is inspired by Carpentries website setup

Videos:

• Cloning/setting up the template
• Filling in the book for the first time
• Making the book available online
• Onboarding new members
• Reviewing the book