DRAFT : EN Editorial Guidelines v.3

This document represents part of our Contributor Guidelines. It is written to ensure that each author, editor, reviewer and translator understands their role. It’s important to us that the experience of all participants is positive and fair. If you have questions about these Guidelines, or if you think any aspect needs updating or improvement, please email our Publishing Assistant.

Welcome

Welcome, bienvenido/a, bienvenue, bem-vindo/a, to the Programming Historian project. Thank you for agreeing to work with us!

Being an editor for Programming Historian means working collaboratively and communicating openly to support the production of lessons that will empower learning and teaching into the future.

Your work will necessarily involve close collaboration with authors, fellow editors, translators and peer reviewers. We are proud to work within a multi-cultural, multi-lingual, and multi-skilled team. As a participant of this project, we ask you to respect our shared code of ethics:

Safe Spaces

The Programming Historian is committed to providing a safe space for the exchange of ideas, where everyone can participate without fear of harassment or abuse. The editor plays a fundamental role in ensuring that space endures. Your responsibilities include upholding our anti-harassment policy at all times and reporting any misconduct. If you need help, please email our Publishing Assistant or our ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca). You can read more about our commitment to safe spaces on the project blog.

Anti-Harassment Policy

This is a statement of the Programming Historian’s principles and sets expectations for the tone and style of all communication between reviewers, authors, editors, and contributors to our public forums.

We are dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinise ideas, ask questions, make suggestions, or request clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca). Thank you for helping us to create a safe space.

This document is designed to help you navigate each phase of our editorial workflow, step-by-step. We’re in the process of changing the way we train new editors, so we’d be grateful for feedback about your onboarding experience: What was good? What was missing? What do you wish you’d learned sooner? Share your thoughts with our Publishing Assistant.

0 First Steps: Orientation, Connections and Set Up

Joining the team

Meet with your Managing Editor
Join our #ph-english Slack channel
Provide/set up a Google-enabled email address for our Google Group
Provide/set up a GitHub username for our Submissions Repository

Our Publishing Assistant will

help you to add your profile to our website via our Jekyll Repository
introduce you to our Submissions Repository
show you the Project Board we use to track lessons as they progress

Your Mentor a fellow editor, will

shadow and support your first editorial tasks
be your first point of contact for advice or questions

Take some time to read

the author, reviewer and translator guidelines pages of our website
the Privileges and Responsibilities of Membership page of our Wiki

Our editorial workflow

uses GitHub — both as a platform for peer discussion and as a site for publication
moves through six key phases: Submission, Initial Edit, Open Peer Review, Recommendation, Copyedit and Publication.

Our lessons are written and edited in Markdown

Sarah Simpkin's lesson Getting Started with Markdown will help you develop this skill
All editing happens within GitHub You may find Text Editors such as Atom or Visual Code Studio useful when composing or revising Markdown We don’t use the Microsoft Office suite or edit with Tracked Changes

First assignment. Your Managing Editor will

assign you your first lesson to edit, according to your interests and experience
share the short abstract and 2-3 core learning outcomes, to give you a general idea of the lesson's objectives and research context introduce you to the author(s) you'll be working with

Communication with authors happens via two channels:

Email: for private/sensitive or logistical correspondences
GitHub Issues: for discussion across all phases of the workflow, including Open Peer Review

1 Submission

1.1 New Issue

In this phase of the workflow, you’ll create a new GitHub Issue to represent the lesson. This Issue will provide a space for communication and collaboration throughout the editorial workflow. It will also contain a link to a live preview of the lesson as the draft progresses.

Create

Navigate to the Issues tab of our Submissions Repository and click "New Issue”
Name the Issue with the lesson’s title — choose a lesson title that is short but descriptive
Insert the title of the lesson and the author's GitHub @username to the Submission Template

Assign

Establish that you will be coordinating this Issue: click on the words "assign yourself”
Co-assign your Mentor. Click on the word "Assignees" and search for their @username

NOTE: Your Mentor will shadow the workflow from start to finish, and will be happy to contribute if they observe that you need support

Label

Click on the word “Labels”
Choose one label appropriate to the language the lesson is written in, “English”
Choose a second to indicate the current phase of the editorial workflow, “Submission”

Submit

Click "Submit New Issue”

Project Board

Navigate to the Project Board
Identify the 'card' representing this lesson in the "Proposals" column
Drag and drop the card into the next column on the right, headed “Submitted Tutorials”
Add your name to the card, and paste in a link to the Issue. The URL will have the following structure: https://github.com/programminghistorian/ph-submissions/issues/xxxx

Concordance

Navigate to the Lesson Concordance Google Sheet and sign in to make edits;

If you are working on an original lesson

Add a new row to the Sheet
Enter the title of your lesson in the correct language column (leave the adjacent cells blank if you are unsure what the translated titles would be)

If you are working on a translation

Locate the lesson’s original title on the Sheet
Check the translation title given is correct, amend if necessary

In both cases

Add a ± plus-minus symbol to indicate that your lesson is in draft
Create a link from the title to the Issue you’ve just created

1.2 New Materials

You’ll receive the new lesson directly from the author, by email or file transfer. It’s your responsibility to upload the various materials (text, images, data files) to the appropriate file directory locations within our Submissions Repository — the following sections will guide you.

We are in the process of revising this part of the workflow, so please contact our Publishing Assistant for technical support if you need help along the way.

Upload lesson text

Start with the lesson’s text. It will be a Markdown file, with the extension .md
Re-name the Markdown file carefully — it needs to correspond directly with the lesson title
Don’t include spaces in the filename; use hyphens instead, e.g., lesson-file-name-here.md
Navigate to the Code tab of our Submissions Repository
Open the directory /en (English)
Find two sub-directories: “drafts” and “published”. Nested within “drafts”, you’ll find two further folders: “originals” and “translations”
Upload the Markdown file into either “originals” or “translations”, as appropriate
To upload the file, click "Add File" then select "Upload Files”.

Prepare Images and Assets

If you have also received images and/or data files as part of the lesson materials, navigate back to the Code tab of our Submissions Repository

Authors should have delivered their image and data files in two separate folders.

Make sure that all the lesson’s images are in one folder, and all the data files are in another
Rename both folders, so that they each share exactly the same name as the lesson file, e.g., lesson-file-name-here

We ask authors to give their image files consistent, meaningful names that help our editors and technicians understand which images are intended to go where. Remind the author that this naming system can be either semantic or sequential, but must be practical.

Take a few minutes to check that the files contained within the two folders are named clearly
Remember that the order of images in the lesson may change during Peer Review and, if so, the image file names will need to be updated

Upload Images and Assets

To upload images, navigate to Images
To upload data files, navigate to Assets
Click "Add File" then select "Upload Files”

NOTE: Neither of these directories have sub-directories – images and assets for all lessons, in all languages, live here.

Support Step Get in touch with our Publishing Assistant when you’ve uploaded the new lesson materials. Her next steps are to add some key elements of YAML metadata and check the Markdown file so that a lesson preview can be generated. When it’s ready, she’ll add a link to the Issue.

Support Steps:

1.2.1 Adding YAML Metadata
1.2.2 Checking Markdown

2 Initial Edit

Your role in the Initial Edit phase is helping the author(s) to shape their lesson so that it is ready for productive peer review. You aren’t expected to be an expert in the lesson’s content, but you should have some familiarity with its subject.

Where to Read

In your web browser, via the live preview
You’ll find a link to a live preview of the lesson in the editor’s initial comment

Alternatively,

In your favourite Text Editor application, such as Atom or Visual Code Studio
You can make a copy the Markdown file from our Submissions Repository

NOTE: Reading in the browser environment, offers you an opportunity to review the text formatted alongside any figure illustrations, graphs and code blocks that are included.

2.1 Editorial Considerations

As you read the lesson, keep in mind usability, sustainability, accessibility and inclusivity

Usability

A good opening paragraph will give readers a summary of the lesson’s learning outcomes.

Refer back to the lesson's objectives: ask yourself whether and how effectively it meets those aims. Are the objectives explicit?
Consider the suitability of the piece as a 'lesson': a means of learning, a tool of teaching
Think about the lesson’s structure: does it progress logically? Do section headings provide clear signposts? We want our lessons to empower and inspire people to learn.
Think about the lesson's intended audience: how might readers perceive its difficulty level?
Are specialist terms defined?
Have pre-requisites of skills and knowledge been explained?
Could identifying further resources or existing Programming Historian lessons enable less-experienced readers to gain that knowledge?

Sustainability

Encourage general methodological overviews — screenshots and specific instructions for using one version of a Graphical User Interface can inadvertently limit a lesson’s longevity
Are software versions and technical dependencies clearly established in the introduction?
Which computing environments were the lesson’s methods tested in?
Have potential errors and challenges been pre-empted? Are troubleshooting steps included?

Accessibility

All images must be concisely captioned and well-described with alt-text
All code must be cut-and-pasteable, rather than shown in screenshots
Choices of data, case studies, and software must involve consideration of access implications

Inclusivity

As an organisation, we are committed to open source values so, where possible, we ask authors to utilise open formats, programming languages and software.

Do the tools and methods taught in the lesson have multi-lingual documentation?
Are resources and images culturally specific? Could they confuse or offend some readers?
Do case studies make use of freely available data sources and examples?
Does the lesson consider bias implicit in the relevant algorithms/tools?

2.2 First-round Feedback

Your feedback We’re committed to supporting all authors whose proposals are accepted to develop lessons that are strong enough for publication. Post your feedback as a comment in the Issue Anchor your comments to particular sections or paragraph numbers (paragraph numbers can be found at the right edge of the text in the lesson's live preview) Consider writing a summary, followed by a list of 'checkboxes' for each individual revision Be constructive, clear and specific Agree on a timeframe with the author to make the suggested revisions — a month is usually reasonable, depending on the amount of work that is needed and their other commitments Remember: GitHub is a public platform — if your feedback is negative, then private communication by email will be kinder

2.3 First-round Revisions

Orientation in the Submissions Repository

Submissions is a dummy repository where we draft and review lessons to prepare them for publication on our live Jekyll site.

You will be granted write-access to our Submissions Repository, so you don’t need to use the Git Pull Request system to make changes to the lesson files you’re editing
Authors will also be able to make direct edits to lesson files in the Submissions Repository
Help the author orientate themselves within the Submissions Repository file directory
Show them how to initiate and ‘commit’ their edits

Editing: a collaborative process

Await the author’s first round of revisions — be patient
Remember that editing is a collaborative process, and will involve dialogue with the author
Be prepared to offer generous support – the depth of editorial work involved at this phase will vary from lesson to lesson
Ask the author to post a comment in the Issue when their draft is ready for your review NOTE: At any time, either of you can review a detailed Commit history, to see previous versions of the draft — just navigate to the file and click “History”. If you need help, ask our Publishing Assistant.

Relabel the Issue

Remove the "Submission" label from the Issue
Replace it with the label "Under Review" to indicate that the lesson has moved into a new phase of the editorial workflow

Update the Project Board

Navigate to the Project Board
Drag and drop the card representing your lesson in “Submitted Tutorials" to the next column on the right, headed "Under Review”

2.4 Identify and Contact Peer Reviewers

When to contact

Are substantive revisions needed before peer review can proceed? The right time to identify and invite two external peer reviewers, depends whether the first-round revisions are major or minor
If you think the required changes are substantial, you may want to wait until you feel satisfied with the revisions
If the required changes are minor, you may feel able to begin considering who to approach immediately, with advance notice of when you think the lesson will be ready for review

Who to contact

As part of our commitment to diversity, we encourage you to make a sufficient effort to invite reviewers who are distinct from you either by gender, nationality, race, age, or academic background
These two short videos may be useful: Finding Peer Reviewers for Technical Tutorials (5:06), Approaching Peer Reviewers for Technical Tutorials (9:06)

How to coordinate requests

Navigate to the Reviewer Tracking Google Sheet, and sign in to make edits
Check the Tracking Sheet to ensure that the reviewer has not been contacted recently by another editor – we limit requests to once per year
Fill in the date you make initial contact, the reviewer’s name, your name, the lesson’s title, and (when you receive it) their response
When you have two peer reviewers agreed, share our reviewer guidelines with them. This will support their understanding of their role, and make our expectations clear

3 Open Peer Review

In our view, Phase 3 is integral to publishing collaborative, productive, and sustainable lessons.

Programming Historian is proud to use an open peer review model
In the spirit of openness, peer review discussion takes place within the Issue’s comments thread, unless the author specifically requests a closed review
We believe open peer review helps maintain civility in the academic community and supports the productive sharing of ideas
However, authors have the right to request a closed peer review, and we have a requirement to respect that right

3.1 Launch

Ask both reviewers to provide/set up their Github @username so they can contribute
Introduce the reviewers to the author(s) by tagging them in a comment

Start the conversation

Explain that you’ve already provided initial feedback on the lesson, and worked with the author to complete a first revision
Share the URL which directs to the live preview, so the reviewers can read it in their browsers
Re-share our reviewer guidelines
Mention that members of our wider community are also invited to offer feedback, which they may contribute to the Issue’s comments thread
Remind participants of our Code of Ethics: feedback must be constructive, and all communication must be respectful, as defined in our Anti-Harassment Policy and guided by our commitment to Safe Spaces

Next steps

Agree on a timeframe with the reviewers to return their comments — a month is usually reasonable
Ask reviewers to post their feedback as a comment in the Issue’s conversation thread
- One approach could be a general feedback summary, followed by specific comments anchored to particular sections or paragraph numbers
Remind the reviewers that paragraph numbers can be found at the right edge of the text in the lesson's live preview

Relabel the Issue

Remove the "Under Review" label from the Issue
Replace it with the label “Author Revising" to indicate that the lesson has moved into a new phase of the editorial workflow

Update the Project Board

Navigate to the Project Board
Drag and drop the card representing your lesson in “Under Review" to the next column on the right, headed "Author Revising”

3.2 Develop

Receive reviews

The immediacy of the conversation thread means that author(s) may see the reviewers’ feedback before you do.
When you see that the first review has been posted, add a comment to acknowledge it and say thank you
Remind the author(s) not to make any revisions until both reviews have been posted — the lesson mustn’t change underneath the second reviewer
After the second review has been posted, prepare a further comment which summarises, reconciles and clarifies the two reviews

Discussion

The author may wish to ask the reviewers questions
There may be disagreements
Some ideas may be absorbed, others may be rejected — that’s okay
Remember: your shared objective is to publish a useful and sustainable technical resource

Your role

Support the author to make decisions
Mediate the dialogue
Help the author to agree revisions and define a clear path forward

Next steps

Negotiate a time frame with the author(s) to finalise their draft — a month or two is usually sufficient
Ask the author to post a comment in the Issue when their final draft is ready for your review
Re-read the lesson
Be prepared to collaborate with the author through a last round of revisions, supporting them to integrate the agreed feedback

4 Recommendation

Phase 4 is about making final preparations ahead of copyediting: you need to choose an image to represent the lesson and collate some additional metadata.

4.1 Image

Select

Source a copyright-free image to represent the lesson
Select a non-offensive, book image (not a photograph) at least 200 pixels width and height
- Image collections of the British Library, Internet Archive Book Images, Library of Congress Maps or the Virtual Manuscript Library of Switzerland are useful places to search

Save two versions

Save it as a .png
Duplicate the .png — you’ll need two versions

Version 1: original

Rename the original so that it shares its name with the lesson file, adding the word “original”, e.g., lesson-file-name-here-original.png

Version 2: duplicate for our “gallery”

Crop to a square, taking care not to remove any key features
Re-size to 200x200 pixels
Convert to greyscale, and adjust the contrast or tonal values if necessary
Re-name the edited image so that it shares exactly the same name as the lesson file, e.g., lesson-file-name-here.png

Upload

Upload Version 2: duplicate to the directory named “gallery”
Upload Version 1: original to the sub-directory “originals” which you will find nested within “gallery”
Click "Add File" then select "Upload Files”

4.2 Metadata

Consider the lesson’s difficulty level NOTE: We tag each lesson either Beginner , Intermediate or Advanced to help our readers evaluate which lessons will suit their skill level. We are in the process of revising guidance about how to define ‘difficulty’. Please contact Sarah Melton if you need assistance.
Consider which research phase or “activity” the lesson supports
- Choose from the activity categories: Acquire; Transform; Analyze; Present; Sustain
Choose a topic group — a meaningful topic tag will help our readers to find lessons that relate to their learning goals
- You’ll find descriptions of each topic in English, French, Portuguese, and Spanish within our Jekyll Repository
- Choose multiple topics if you need to If none of the existing topics sound right, you can suggest a new one

4.3 Author info

An abstract of their lesson, 1-3 sentences NOTE: The abstract will form the summary available beneath the lesson title in our Lesson Index and will also be included within the lesson’s header.
A brief bio*, 1 sentence, e.g., [Author’s Name] is an assistant professor in the Department of [Subject] at the University of [City] NOTE: *A bio is only needed if this is the author’s first lesson for Programming Historian
Their ORCiD, if they have one
Their Permission to Publish. Ask the author to post a comment in the Issue giving their permission for us to publish their lesson:

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español|em português to publish the tutorial in this Issue (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

- Authors can adapt their statement from this template if they wish

4.4 Checklist

Collate the information in this Checklist and post it as a comment in the Issue.

Difficulty
Activity
Topic
Abstract
Bio
ORCiD
Permission to Publish

5 Copyedit

Phase 5 is a Support Step performed either by our Publishing Assistant or a freelance copyeditor. Before copyediting begins, you need to complete a few administrational tasks.

Re-label the Issue

Remove the "Under Review" label from the Issue
Replace with the "In Copyedit" label, to indicate that the lesson has moved into the next phase of the editorial workflow

Update the Project Board

Navigate to the Project Boardd
Drag and drop the card representing your lesson from the "Under Review" column, to the next column on the right "In Copyedit”

Next Steps

Your Managing Editor will assign a copyeditor to the lesson
The Copyeditor will be introduced to you and the author via a comment in the Issue
- The Copyeditor may be an internal member of the team, or a freelancer
They’ll join the conversation thread to support the next phase of the editorial process
Be prepared to answer questions, and contribute to points of discussion as the copyediting process develops

Support Step Our copyediting workflow involves:

Checking the text for clarity, readability, typing mistakes and grammatical errors
A full review of the Markdown file to check the lesson’s layout and structure
Replacing all external links included in the lesson with archival perma.cc hyperlinks Our Publishing Assistant will undertake/oversee this process. They’ll let you and your Managing Editor know when Phase 5 is complete.

Support Steps:

5.1 Copyedit
5.2 Typesetting
5.3 Archival hyperlinks

Support Step A Managing Editor’s final review ahead of publication, ensures that all lessons meet our high standards of: usability, sustainability, accessibility and inclusivity. In Phase 6, your Managing Editor will add the author’s bio and ORCiD (if applicable) to our directory, request a unique Digital Object Identifier (DOI), and move the files from Submissions to our live Jekyll Repository. They’ll let you know when the lesson has been published.

Support Steps:

6.1 Managing Editor’s Review
6.2 Move Files

6 Publication

6.3 Thanks and Promotion

Congratulations! The lesson is now published!

You have some very important final tasks:

Say thank you

Say “thank you” to your collaborators – via a comment in the Issue, or by email
- It is particularly important to thank the author(s) and peer reviewers for their contributions

Initiate and activate promotion

We use a Twitter Bot as a tool to regularly remind our followers about old (and new) lessons
To add this lesson to the pipeline, you’ll need our Twitter Bot Google Sheet
Ask your Mentor for the access link, and sign in to make edits
Scroll to the foot of the page, create a new row and enter the following:
- “message_one” (column A) a short Tweet to be posted early in the week
- “message_two” (column B) a short follow-up Tweet to be posted later in the week
- “link” (column C) a live link to the published lesson
- Leave column D blank and untouched – this field is used by the Bot to log its progress

NOTE: Our Bot promotes one lesson a week at random, which means it may be months until your lesson is promoted, so this step mustn’t replace your own promotion of the lesson.

Encourage the author to participate in promotion. Remind them to:

Tweet at least 3 times about their lesson, including a link.
Retweet our Tweets about their lesson (‘liking’ does not help spread the word)
Promote their lesson in presentations or publications about their research
Link to it in blog posts when relevant
Add it to lists of resources in relevant repositories (e.g., Wikipedia, community groups)

NOTE: Investing energy into promoting a lesson, encourages its use by helping learners and teachers to find it.

Finally, Thank you for all your hard work. We are enormously grateful for your time and commitment.