Donate to Programming Historian today!

Contents

Our publishing workflow moves through eight phases: Proposal, Submission, Initial Edit, First Revision, Open Peer Review, Second Revision, Sustainability + Accessibility, and Publication. The development of both original and translated lessons is supported by the professional services of our Publishing Manager, guided by our Managing Editors, with the expertise of a cohort of volunteer editors from our project team.

Overview of Phases, Responsibilities, and Timeframes

Phase Who is responsible? Expected timeframe:
0 Proposal Managing Editor + their editorial team 30 days feedback
45 days submission
1 Submission Publishing Manager 14 days
2 Initial Edit Editor 30 days
3 First Revision Author/translator + editor 30 days
4 Open Peer Review Reviewers + editor 30 days
5 Second Revision Author/translator + editor 30 days
6 Sustainability + Accessibility Publishing Manager (+ copyeditor) 30 days
7 Publication Managing Editor + Publishing Manager 14 days

Details of Phases, Responsibilities, Timeframes, and Processes & Activities

Phase 0 Proposal

Who is responsible? Expected timeframe Process & activities
Managing Editor + their editorial team 30 days feedback
45 days submission
• Managing Editor receives proposal forms.
• Proposal forms are circulated for feedback from the editorial team within 30 days.
• Note: Proposals are considered on the basis of how well they serve the needs of the community, and whether they support our journal’s ambitions of openness, global access, multilingualism and sustainability.
• Managing Editor replies to authors/translators to either reject the proposal and share feedback, or invite submission.
• Managing Editor opens a new GitHub issue to represent the successful proposal, assigning an editor, and agreeing a submission date within 45 days.
• Note: This issue will provide a space for communication and collaboration throughout the publishing workflow. Labels will be used to indicate the lesson’s progress. The Publishing Manager will post a comment at the beginning of each phase to clarify What’s happening now?

Phase 1 Submission

Who is responsible? Expected timeframe Process & activities
Publishing Manager 14 days
• Publishing Manager receives and processes submission materials.
• Markdown files are checked, and key elements of metadata are added.
• Figures are resized and renamed according to our requirements and conventions
• Data assets are checked and processed.
• Publishing Manager posts a comment to the GitHub issue, providing locations of all key files, as well as a link to a live ‘in browser’ preview, where contributors will be able to read the lesson as the draft progresses.
• Publishing Manager sends new contributors an invitation to join the repository as Outside Collaborators, granting them direct write access.
• Publishing Manager will liaise with author/translator to resolve any queries raised during file processing, and to work through any initial adjustments required.

Phase 2 Initial Edit

Who is responsible? Expected timeframe Process & activities
Editor 30 days
• Editor reads the submission, considering how well it meets our journal’s ambitions of openness, global access, multilingualism and sustainability.
• Editor considers the lesson’s level of difficulty against our matrix.
• Editor shares initial feedback as a comment in the GitHub issue, anchoring specific comments to sections or paragraphs (referring to numbers at the right margin of the lesson preview) to support the author’s/translator’s revisions in Phase 3.

Editorial Principles

Our principles Key considerations  
Openness
• Does this lesson centre open source software, open programming languages, and open access datasets?
• If the method involves any proprietary software or commercial tools, we strongly recommend authors present these alongside open source alternatives, and cost-free options.		  
Global access
• Does this lesson outline technical prerequisites clearly, and consider potential limitations of access to methods, software or tools?
• Remind authors that our readers work with different operating systems and have varying computational resources.
• Is accessibility embedded within lesson?
• Our readership have different abilities, and varying access needs. Directive language should avoid using sight as a metaphor for understanding; visuals, plots, and graphs must be accompanied by concise captions, and alt-text; tabular data and code must be provided in Markdown and raw form.		  
Multilingualism
• Has the author chosen methods, tools, and datasets that can be applied or adapted for use in languages other than English?
• Our strong preference is to publish lessons that will be practicable in multilingual research-contexts, and future translation.
• Has this author attempted to localise their translation by replacing datasets or use case materials in the translation language to improve usability for the new audience?
• If this is a translation to English, consider encouraging the author to keep non-English datasets in place, to help our Anglophone communities learn to work with multilingual data and research materials.		  
Sustainability
• Does this lesson successfully prioritise reflections, contextual discussions and overviews of practical steps over click-by-click instructions?
• This emphasis helps to ensure lessons remain useful beyond present-day graphical user interfaces and current software versions. Encourage authors to anticipate challenges readers may face, and guide troubleshooting.
• Does the author specify which computational environment, programming languages, packages and software versions the lesson has been developed for and tested within?
• Ask authors to include clear citations to resources, datasets, and software.		  

Phase 3 First Revision

Who is responsible? Expected timeframe Process & activities
Author/translator + editor 30 days
• Editor + author/translator agree a timeframe for the author/translator to make the suggested revisions (30 days is usually reasonable).
• Author/translator revises the lesson.
• Author/translator posts a comment in the issue to confirm when the revised draft is ready for the editor’s review.
• Note: Revision is a collaborative process, involving dialogue. The depth of editorial work involved will vary from lesson to lesson.
• Editor begins coordinating peer reviewers to participate in Phase 4. The first step is to systematically contact the Publishing Manager, who will provide the details of available reviewers from our pool of volunteers. If there are none, the Managing Editor can support the editor to make direct approaches.
• We are committed to inviting a broad range of community perspectives, and we strive to maintain a diversity of gender, nationality, race, age, and academic background among our contributors. Open Peer Review should remain an inclusive space in which peers can teach and learn from each other generously, as equals.

Phase 4 Open Peer Review

Who is responsible? Expected timeframe Process & activities
Reviewers + editor 30 days
• Reviewers share their feedback as a comment in the issue thread within 60 days.
• Editor summarises the two reviews so that the author/translator has a clear sense of the revisions to work through in Phase 5.

Phase 5 Second Revision

Who is responsible? Expected timeframe Process & activities
Author/translator + editor 30 days
• Editor + author/translator agree a timeframe for the author/translator to make the suggested revisions (30 days is usually reasonable).
• Author/translator revises the lesson.
• Author/translator posts a comment in the issue to confirm when the revised draft is ready for the editor’s review.
• Editor re-reads the lesson to confirm that all agreed revisions are complete.
• Managing Editor reads the lesson to confirm if it should be moved to Phase 6.

Phase 6 Sustainability + Accessibility

Who is responsible? Expected timeframe Process & activities
Publishing Manager (+ copyeditor) 30 days
• Copyediting to check the text for clarity of expression, typing mistakes and grammatical errors.
• Typesetting to ensure consistent layout.
• Generating archival hyperlinks.
• Checking of files and metadata.
• Assigning a DOI.
• Collating copyright agreements.

Phase 7 Publication

Who is responsible? Expected timeframe Process & activities
Managing Editor + Publishing Manager (+ editor post-publication) 14 days
• Publishing Manager stages files for publication.
• Managing Editor re-reads the lesson, to provide final feedback or suggest additional revisions.
• Managing Editor approves the lesson for publication.
• Publishing Manager initiates announcement and schedules promotion of the new lesson.
• Publishing Manager shares suggested citation and social media announcement links with all contributors to close the issue.