-
Notifications
You must be signed in to change notification settings - Fork 114
Mermaid Diagrams
charlottejmc edited this page Sep 19, 2024
·
4 revisions
This page is an archive of the mermaid diagrams we previously developed to illustrate the publishing workflow. They have now been replaced with a tabular structure.
Overview of Editorial Workflow
Phase 0 Proposal
Phase 1 Submission
Phase 2 Initial Edit
Phase 3 Revision 1
Phase 4 Open Peer Review
Phase 5 Revision 2
Phase 6 Sustainability Accessibility
Phase 7 Publication
timeline
Title Workflow overview
section Phase 0 <br> Proposal
section Phase 1 <br> Submission
section Phase 2 <br> Initial Edit
section Phase 3 <br> Revision 1
section Phase 4 <br> Open Peer Review
section Phase 5 <br> Revision 2
section Phase 6 <br> Sustainability + Accessibility
section Phase 7 <br> Publication
timeline
Title Responsibilities + Timeframes
Section Phase 0 <br> Proposal
Who's responsible? : Managing Editor
Expected timeframe? : 14 days feedback : 90 days submission
Section Phase 1 <br> Submission
Who's responsible? : Publishing Team
Expected timeframe? : 7 days
Section Phase 2 <br> Initial Edit
Who's responsible? : Editor
Expected timeframe? : 30 days
Section Phase 3 <br> Revision 1
Who's responsible? : Author
Expected timeframe? : 30 days
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers
Expected timeframe? : 60 days
Section Phase 5 <br> Revision 2
Who's responsible? : Author
Expected timeframe? : 30 days
Section 6 <br> Sustainability + Accessibility
Who's responsible? : Publishing Team
Expected timeframe? : 21 days
Section Phase 7 <br> Publication
Who's responsible? : Managing Editor
Expected timeframe? : 14 days
timeline
Section Phase 0 <br> Proposal
Who's responsible? : Managing Editor
Expected timeframe? : 14 days feedback : 90 days submission
timeline
Section Phase 1 <br> Submission
Who's responsible? : Publishing Team
Expected timeframe? : 7 days
timeline
Section Phase 2 <br> Initial Edit
Who's responsible? : Editor
Expected timeframe? : 30 days
timeline
Section Phase 3 <br> Revision 1
Who's responsible? : Author + Editor
Expected timeframe? : 30 days
timeline
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers + Editor
Expected timeframe? : 60 days
timeline
Section Phase 5 <br> Revision 2
Who's responsible? : Author + Editor
Expected timeframe? : 30 days
timeline
Section Phase 6 <br> Sustainability + Accessibility
Who's responsible? : Publishing Team
Expected timeframe? : 21 days
timeline
Section Phase 7 <br> Publication
Who's responsible? : Managing Editor
Expected timeframe? : 14 days
timeline
Title Phase 0 Proposal
Section Overview
Who's responsible? : Managing Editor
Expected timeframe? : 14 days feedback : 90 days submission
timeline
Section Process
Circulate for feedback : Managing Editors receive lesson proposals by email. In this phase of the workflow, they circulate abstracts within their team. They will request editors' feedback on the suitability, quality and interest of the proposed lesson, and ask who may be available to edit it. : Reply to Author + Define Revisions : Reply to Author + Reject
Invite Submission. Open New Issue + Assign Editor : Managing Editors will create a new GitHub Issue to represent the lesson. The Issue will provide a space for communication and collaboration throughout the editorial workflow. For now, it represents a placeholder and an agreement that the submission is invited within 90 days of acceptance.
timeline
Title Phase 1 Submission
Section Overview
Who's responsible? : Publishing Team
Expected timeframe? : 7 days
timeline
Section Process
New Materials : In this Phase, our Publishing Team will receive and upload the new lesson materials. They'll check the Markdown file, and add some key elements of metadata. They'll also check any accompanying images and assets, ensuring each element meets our requirements.
New Comment : Next, our Publishing Team will add a new comment to the lesson's GitHub Issue. This comment will provide the locations of all key files, as well as a link to a live preview where contributors can read the lesson as the draft progresses.
timeline
Title Phase 2 Initial Edit
Section Overview
Who's responsible? : Editor
Expected timeframe? : 30 days
timeline
Section Process
Read : Read for <br> Usability Sustainability Accessibility Inclusivity : Consider Difficulty
Feedback : Post your feedback as a comment in the Issue : Anchor your comments to particular sections or paragraph numbers (found at the right edge of the text in the lesson's live preview) : Define Revisions or Reject
timeline
Section Editorial Considerations
Usability : Usable lessons summarise learning outcomes in an opening paragraph : Are structured logically, with clear section headings and meaningful signposting : Are robust, with clear instructions and thoroughly-tested code : Keep within the word limit (8,000 words including code)
Sustainability : Sustainable lessons cite software versions, specify technical dependencies : Provide general methodological narratives rather than interface-specific instructions : Anticipate challenges, support trouble-shooting
Accessibility : Accessible lessons caption images concisely, describe visuals with detailed alt-text : Provide cut and pasteable code, rather than showing it in screenshots : Keep accessibility in mind when choosing data, case studies, and software : Comply with our difficulty matrix to specify prerequisite knowledge, define technical terms, rate the complexity of install and set-up, include, outline, or reference trouble-shooting steps, and state where and how knowledge beyond the lesson's scope can be learned.
Inclusivity : Inclusive lessons use open formats, open programming languages and open-source software : Consider implicit bias of algorithms and tools : Identify multilingual external resources and software documentation wherever possible : Are explicit if recommending learning content that is not available in the lesson's native language.
timeline
Section Difficulty matrix
difficulty 1 <br> Beginner : No prior knowledge required : All steps are clearly defined : Specialist or technical terms are defined : Software packages are easy to install (no “known issues”) : Challenges that readers might encounter are anticipated, and clear trouble-shooting steps included : Further Programming Historian lessons (or external resources) for advancing new skills may be referenced.
difficulty 2 Intermediate : Some prior knowledge is required : Existing Programming Historian lessons (or external resources) to empower less experienced readers to gain that knowledge are identified : Key steps are defined, all steps are outlined : Specialist or technical terms established by beginner lessons are used in context, while any new terms are defined : Software install and set-up may be subject to “known issues” : Challenges that readers might encounter are anticipated, and trouble-shooting steps are outlined
difficulty 3 Advanced : Significant prior knowledge and applied experience required : Confident ability to infer intermediate-level steps expected : Specialist or technical terms are used throughout, new concepts are explained : Software and packages may be known for their complexity to install and set-up : Challenges that readers might encounter are anticipated, and trouble-shooting steps are referenced.
timeline
Title Phase 3 Revision 1
Section Overview
Who's responsible? : Author + Editor
Expected timeframe? : 30 days
timeline
Section Process
Revise : Agree on a timeframe for the author to make the suggested revisions - a month is usually reasonable : Ask them to post a comment in the Issue when their draft is ready for your review.
Respond : Remember that editing is a collaborative process, and will involve dialogue : Be prepared to offer generous support – the depth of editorial work involved at this phase will vary from lesson to lesson
Reviewers <br> 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.
Reviewers <br> 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 : We created two short videos which may be useful (links below).
Finding Peer Reviewers for Technical Tutorials (5:06)
Approaching Peer Reviewers for Technical Tutorials (9:06)
timeline
Title Phase 4 Open Peer Review
Section Overview
Who's responsible? : Reviewers + Editor
Expected timeframe? : 60 days
timeline
Section Process
About : In our view, Phase 4 is integral to publishing collaborative, productive, and sustainable lessons. : Open peer review helps maintain civility in the academic community and supports the productive sharing of ideas : In the spirit of openness, peer review discussion takes place within the Issue’s comments thread unless an author specifically requests a closed review.
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 : 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 the lesson in their browsers : Share our Reviewer Guidelines : Mention that members of our wider community are also invited to offer feedback : Remind all participants of our Code of Conduct. : Agree on a timeframe with the reviewers to return their comments — a month is usually reasonable.
Develop : Ask reviewers to post their feedback in the Issue. : 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.
Summarise + Support : After the second review has been posted prepare a response which summarises, reconciles and clarifies the two reviews. : Your role now, is to support the author to agree revisions and define a clear path forward. : Remember that the author may wish to ask the reviewers questions : Some ideas may be absorbed, others may be rejected — that’s okay : Your shared objective is to publish a useful and sustainable technical resource for the community.
Reviewer Guidelines Code of Conduct
timeline
Title Phase 5 Revision 2
Section Overview
Who's responsible? : Author + Editor
Expected timeframe? : 30 days
timeline
Section Process
Revise : Negotiate a time frame with the author(s) to finalise their draft — a month is usually sufficient : Ask the author to post a comment in the Issue when their final draft is ready for your review.
Respond : Re-read the lesson : Be prepared to collaborate with the author through a last round of revisions, supporting them to integrate the agreed feedback.
timeline
Title Phase 6 Sustainability + Accessibility
Section Overview
Who's responsible? : Publishing Team
Expected timeframe? : 21 days
timeline
Section Process
About: In this Phase, our Publishing Team will coordinate a series of tasks and checks to ensure the sustainability and accessibility of the lesson.
Copyedit <br> (original lessons only) : Check for clarity, readability, typing mistakes and grammatical errors
Typesetting, metadata + YAML : Review of the lesson’s layout and structure
Archival hyperlinks : Replacement of external links included in the lesson with archival perma.cc hyperlinks
Copyright : Declaration forms to acknowledge authorial/translators' copyright, and formally grant ProgHist Ltd permission to publish
DOI : Assignment of a unique DOI (Digital Object Identifier)
timeline
Title Phase 7 Publication
Section Overview
Who's responsible? : Managing Editor
Expected timeframe? : 14 days
timeline
Section Process
Managing Editors' Review : This is a final read of the lesson to ensure that it meets our high standards of usability, sustainability, accessibility and inclusivity. : If the Managing Editor does not feel satisfied, they will refer the lesson back to the editor and author for further revisions.
Move Files : The Managing Editor will transfer the lesson files from our Submissions Repository to the corresponding locations in Jekyll.
Activate Promotion : Upon publication, the Managing Editor will coordinate with our Publishing Manager to initiate promotion of the new lesson.