Editing together#

Editing the book together is one of the core ideas behind Our Handbook: the purpose is to ensure that everyone knows where everything is, and has the chance to share their knowledge and make sure that the group works for them. We really recommend editing the book together. Here we provide some guidance for how you might want to organise doing that.

Preparations#

We recommend nominating 1-2 people from the group to do the initial set up of the Our Handbook template for your group and admin. This should be done ahead of other people working on the handbook, i.e. in advance of a book sprint where you fill it in together.

Checklist

  • Make your own copy of this repo

    • Fork the repo (if your group doesn’t have a GitHub organisation, perhaps make one and fork to there).

    • Make all members of your team collaborators of the forked repo (and/or members of the GitHub organisation).

    • Ensure the group agrees on what license your handbook materials will use. By default it will use the CC-BY license (as you will copy it when you copy this repository). If you’d like to use a different license instead, replace the LICENSE.md file in the root directory before you start making other changes.

    • Edit the README.md and CONTRIBUTING.md files in the root of the repo, according to the FIXME instructions in html comments (that look like this <!-- FIXME: instructions-->). You’ll only be able to see these in a text (markdown) editor. Note: These look different to the other FIXME instructions as described in [editing-instructions][contributing-fork] because they must be invisible on the Our Handbook repository.

  • Choose a day or two for an away day/book sprint. This can be done synchronously or asynchronously, and virtually or in the same space.

    • Find (a) time(s) when everyone can attend

    • Book a room if necessary

    • Organise lunch/snacks/drinks

    • If GitHub is new to the team, organise a GitHub training session ahead of time.

  • Ensure you understand how team members will be editing the handbook together.

  • Ensure you have up-to-date photos for the handbook, consider organising a group photo + individual photos if possible.

  • Prepare some issues to kick-start the conversation in your new fork, e.g.:

    • Create a handbook mega-check-list with every section that you might want to put in the book.

    • Fill in the “Our Team” section (each person fills in their own section).

    • Fill in the “Current Projects” section (nominate a person per project).

Plan for the day(s)#

Introduction (~40 mins)#

  • Welcome

  • Guide of the repository, especially:

    • where to find the away-day contribution guidelines, and what they are.

    • where to find the issues

    • Maybe practice communicating on GitHub (e.g. in “discussions”).

  • Go through your handbook mega-check-list issue and agree on what sections should be in your finished handbook, and sort them roughly by priority (e.g. “must-have”, “nice-to-have”)

  • Create issues together for the first task each person will do, and link them to the mega-check-list

Working sessions (~2 hours each)#

  • Set goals (remind of process, e.g. make/comment on issues)

  • Use a pomodoro timer to work for three-to-four sets of 25 minutes (if working virtually, you could use cuckoo.team or marinara timer

  • Use 5 minute breaks between sessions to check in with everyone/answer questions, and continually set goals and celebrate achievements.

Suggested mega-check-list#

You can copy and paste the following into a GitHub mega-check-list as a starting point.

- [ ] Update GitHub-only files
    - [ ] README
    - [ ] LICENSE 
    - [ ] CONTRIBUTING
- [ ] Fill out templates
    - [ ] Welcome
    - [ ] Our Team
    - [ ] Research Interests
    - [ ] Projects
    - [ ] Research Environment
    - [ ] Resources
- [ ] Final tidying
    - [ ] Delete the "Guide" section