Phase 2 Initial Edit

---

Contents of this page:

• Overview
• Editorial Considerations
• Difficulty Matrix

---

Overview

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 Considerations

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 case study examples with materials in the translation language to improve usability for the new audience? If this is a translation to English, encourage the author to keep non-English datasets and case study examples 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 case study sources, datasets, and software.

Difficulty Matrix

How does Programming Historian define difficulty?

When assigning lesson difficulty, it is useful to consider: how much prerequisite knowledge is expected; whether and how specialist or technical terms are used and defined; the relative complexity of install and set-up; whether trouble-shooting steps are included, outlined, or referenced; where and how knowledge beyond the lesson's scope can be learned (through existing Programming Historian lessons, other written documentation), or whether applied experience is necessary.

• Prerequisite knowledge
• Handling of specialist/technical terms
• Complexity of install and set-up
• Support for troubleshooting
• Guidance for further learning (towards or beyond the lesson)

Level	Description
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 are included - Further Programming Historian lessons (or external resources) for advancing new skills may be referenced
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
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