As part of the Open Book Futures Experimental Publishing Group's pilot project around Deep Maps: Blue Humanities, we are experimenting with using GitHub for peer review. This REVIEWME file contains instructions and recommendations for this peer review process. This is an experimental and evolving process so please treat these instructions as a guide rather than a rigid set of rules.
We are using GitHub issues for peer review as a replacement for the annotations or comments that would form the basis of a peer review using a traditional Microsoft Word-bound peer review. The GitHub interface allows a user to log a new issue on whatever aspect of the repository that they want in a free-text field that supports Markdown and the attaching of files like screenshot images. These instructions therefore use 'issue' throughout despite the slightly derogatory implications of that word in the context of a peer review process.
The GitHub repository is structured with each chapter of the prospective book in a different directory. In each chapter's directory, there is another directory containing the 'paragraphs' (the fragmentary text that will form the basis of the book) in Markdown format. These are the principal content of the book: a reviewer should read through them carefully, either keeping notes in another piece of software or creating line-by-line issues (see below) as you go.
To submit an issue, click 'New issue' on the issues page.
This page invites you to add a title which should be a short summary of your comment and a description which should be your peer review comment in full with any appropriate links or screenshots or additional material. Once you've finished and you've added any appropriate labels, click 'Submit new issue' at the bottom of the page.
Your issue will be added as a new 'open' issue on the issues page.
To submit an issue about a specific line of text, click on 'Code' while reading one of the paragraphs to bring up the code view. Click on the '...' button that appears to the left of the line of text that you want to comment on and select 'Reference in new issue' in the dropdown menu that appears.
This will automatically take you to the new issue form and prepopulate the description with a hyperlink to the specific line you wish to comment on. Follow the above process for adding issues generally to complete submitting your issue.
You can also use the same dropdown menu to 'Copy permalink' to get a hyperlink that links to the specific line of text that you want to comment on.
We are also experimenting with using labels to tag peer review issues. When logging an issue, click on 'Labels' to show the list of existing labels. You can either use one or more of these labels or click on 'Edit labels' to add a new label.
Labels will allow peer reviewers to distinguish between types of comments i.e. whether they apply to content of the text or to styling of the book, whether they ask a question rather than supply a comment, whether they refer to a single chapter or to the book as a whole.
You can also comment on existing peer review issues. Click on an open issue and scroll down to find the 'Add a comment' box. You can type whatever comment you want to make and click 'Comment' to add your comment. We find commenting on comments both productive and satisfying way of bringing the spirit of deep mapping to peer reviewing.