diff --git a/_data/snippets.yml b/_data/snippets.yml index 365018bad..7e5692e87 100644 --- a/_data/snippets.yml +++ b/_data/snippets.yml @@ -153,8 +153,8 @@ menu-contribute-review: link: /pt/directrizes-revisor menu-contribute-write: en: - title: Author Guidelines - link: /en/author-guidelines + title: Lesson Framework + link: /en/lesson-framework es: title: Guía para autores link: /es/guia-para-autores @@ -179,8 +179,8 @@ menu-contribute-translate: link: /pt/directrizes-tradutor menu-contribute-edit: en: - title: Editor Guidelines - link: /en/editor-guidelines + title: Publishing Workflow + link: /en/publishing-workflow es: title: Guía para editores link: /es/guia-editor diff --git a/en/author-guidelines.md b/en/author-guidelines.md deleted file mode 100755 index 523acea5d..000000000 --- a/en/author-guidelines.md +++ /dev/null @@ -1,348 +0,0 @@ ---- -title: Author Guidelines -layout: blank -redirect_from: - - /new-lesson-workflow - - /author-guidelines -skip_validation: true ---- - -# Author Guidelines - -{{ site.data.snippets.write-a-lesson-image-alt[page.lang] }} -

Step 1: Proposing a New Lesson

-

Step 2: Writing and Formatting a New Lesson

-

Step 3: Submitting a New Lesson

- - -These guidelines have been developed to help you understand the process of creating a tutorial for the English *Programming Historian*. They include practical and philosophical details of the tutorial writing process, as well as an indication of the workflow and the peer review process. If at any time you are unclear, please [email the managing editor](mailto:english@programminghistorian.org). - -## Step 1: Proposing a New Lesson - -
-Our English journal will open its next annual submission window in October 2025. In the meantime, you may find it useful to consult our past call for proposals (closed in January 2025). Submissions to our Spanish, French and Portuguese journals are open year-round. -
- -You can get a sense of what we publish by looking through our [published lessons]({{site.baseurl}}/en/lessons), reading our [reviewer guidelines]({{site.baseurl}}/en/reviewer-guidelines) or browsing [lessons in development](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/en/drafts). Please also take a moment to check our [Lesson Concordance document](https://docs.google.com/spreadsheets/d/1vrvZTygZLfQRoQildD667Xcgzhf_reQC8Nq4OD-BRIA/edit#gid=0) to see which methods we have already covered in our published or forthcoming lessons. - -If your proposal is accepted, an editor will create a "Proposal" page on our [submissions website](https://github.com/programminghistorian/ph-submissions/issues) with the lesson's working title and proposed learning outcomes. This serves to mark the work in progress. To ensure timely publication, authors should submit their draft article within 90 days. - -During this 90 day period, your point of contact will be the managing editor or an editor delegated at the managing editor's perogative. - -## Step 2: Writing and Formatting a New Lesson -This style guide lays out a set of standards for authors to use when creating or translating English-language lessons for *Programming Historian*. By using it, you help us ensure content is consistent and accessible. - -It is presented in three sections which should be read before and after writing: - -* A. Style and Audience -* B. Specific Style Guidelines -* C. Formatting Guidelines - -## A. Style and Audience -This first section is concerned with big-picture matters of style which will help you make decisions that meet the needs of our audience and editors. They include basic information on style and tone, open access and open source values, information on writing for a global audience, writing sustainably, and making smart choices about data used in lessons. Read this section when planning your lesson. Read it again before submitting to make sure your lesson meets these requirements. - -### Language and Style -* Tutorials should not exceed 8,000 words (including code). -* Keep your tone formal but accessible. -* Talk to your reader in the second person (you). -* Adopt a widely-used version of English (British, Canadian, Indian, South African etc). -* The piece of writing is a "tutorial" or a "lesson" and not an "article". - -### Open Source, Open Access -*Programming Historian* is committed to open source values. All lessons must use open source programming languages and software whenever possible. This policy is meant to minimize costs for all parties, and to allow the greatest possible level of participation. - -Authors retain copyright and grant the journal the right of first publication, with the work simultaneously licensed under the Creative Commons - Attribution 4.0 International [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en) License. Authors have permission to publish and distribute their work online in institutional/disciplinary repositories or on their personal homepage. - -We ask authors and translators to complete [a declaration form](/assets/forms/Authorial-copyright-and-publishing-rights.pdf) to acknowledge copyright and grant permission to publish. Please send it to our [Publishing Assistant](mailto:admin@programminghistorian.org). - -### Write for a Global Audience -*Programming Historian* readers live all around the world. Authors can and should take steps to write their lesson accessibly for as many people as possible. Follow these global-facing guidelines: - -* Write for someone who doesn't live in your country or share your beliefs. - -* **Technical Terms:** should always be linked to [Wikipedia](https://www.wikipedia.org/) or a suitably reliable dictionary or sustainable website in the first instance. A technical term is any word that a person on the street may not know or understand. -* **Cultural References**: mentions of persons, organisations, or historical details should always come with contextual information. Assume no prior knowledge, even of widely known cultural references (eg, [the Beatles](https://en.wikipedia.org/wiki/The_Beatles)). Use generic terms rather than trademarks (tissue rather than Kleenex). Links to [Wikipedia](https://www.wikipedia.org/) should be used liberally. Be aware that historical events often have different names in different countries. -* **Idioms**: Avoid jokes, puns, plays on words, idiomatic expressions, sarcasm, emojis, jargon, terms unique to your dialect, or language that is more difficult than it needs to be. -* **Geography**: when referencing places, be specific. Does "south-west" mean Valencia? Canada? Africa? Always write out the full name of the area the first time you use it. -* **Multi-lingual**: when choosing methods or tools, make choices with multi-lingual readers in mind – especially for textual analysis methods, which may not support other character sets or may only provide intellectually robust results when used on English texts. Where possible, choose approaches that have multi-lingual documentation, or provide multi-lingual references for further reading. This will help our translators. -* **Racial and Ethnic Language**: use racial terminology carefully and with specificity. Historic terms no longer in use should be used only in their historical context and only when necessary. Use racial terms as adjectives and not nouns: white people rather than "whites", an Asian woman rather than "an Asian". Be aware that terms may be understood differently in different countries and what you have learned to be correct or sensitive may be culturally specific to your country (eg, not all people with African ancestry are "African Americans". Some of them are African, or black British, or Caribbean, etc). Likewise, readers in the UK will understand "Asian" (India, Pakistan, Bangladesh) differently than those in North America (eg China, Japan, Vietnam, Thailand). -* **Visual Representations**: choose primary sources, images, figures, and screen shots, considering how they will present themselves to a global audience. -* **Computing resources**: if your lesson requires relatively substantial computing resources, include an alert warning after the Table of Contents to inform the readers. Please be specific and translate the requirements into real terms (e.g. "You need at least 8GB of RAM to finish this lesson", "This lesson uses large files (up to 2GB)", etc. ). State if readers need admin access to install software. - -### Sustainable Writing -*Programming Historian* publishes lessons for the long-term. Please follow these sustainability guidelines when writing: - - * **As General as Possible, but No More**: focus on methodologies and generalities, not software/interface specifics (eg avoid telling users to "click the X button", which may be different in future versions). - * **Reduce Reliance on Unsustainable Elements**: use screenshots sparingly and with purpose. Interfaces change frequently and future readers may be confused. Chose external links with the future in mind. Does the site you are linking to change often? Will it exist in ten years? - * **Specify Versions if they are Important**: be clear about any version-specific details readers will need to know in order to follow your lesson. Eg, do you need Python v.2, or will any version be fine? - * **Point to Documentation**: direct readers to reliable documentation where possible. Provide general guidance on how to find the documentation if new versions are probable in future. - * **Copies of Data**: all data used in lessons must be published with the lesson on *Programming Historian* servers along with your lesson. You must ensure you have the legal right to publish a copy of any data that you use. Data files should use open formats. - -Authors should consult our [lesson retirement policy]({{site.baseurl}}/en/lesson-retirement-policy) for information on how the editorial team manages lessons that have become out-of-date. - -## B. Specific Writing Guidelines -This second section covers more specific matters of writing style, such as which words to use, or how we use punctuation, or what format to use for dates or numbers. Read this section before and after writing your draft. - -### Dates and Time - * For centuries, use eighteenth century not 18th century. Avoid national-centric phrases such as "long eighteenth century" which have specific meaning to British eighteenth century specialists, but not to anyone else. - * For decades, write the 1950s (not "the 50s" or "the fifties"). - * Compress date sequences as follows; 1816-17, 1856-9, 1854-64. - * For dates written in numeric form, use the format YYYY-MM-DD, which conforms to the standard ISO 8601:2004. This avoids ambiguity. - * Use BCE/CE not BC/AD for dates (eg 325BCE). - * 1am, 6:30pm. Not 10 o’clock. - -### Numbers - * Spell out from one to nine; integers above 10. - * Use a consistent format if the boundary outlined above is crossed within a single sentence (five apples and one hundred oranges; 5 apples and 110 oranges). - * Use commas (not periods/full stops) between groups of three digits in large numbers (32,904 not 32904). Exceptions: page numbers, addresses, in quotation, etc. - * Use numerals for versions (version 5 or v.5) or actual values (eg, 5%, 7″, $6.00). - * Always use the symbol % with numerals rather than the spelled-out word (percent), and make sure it is closed up to number: 0.05%. - * Use [LaTeX formatting for mathematical formulae](https://davidhamann.de/2017/06/12/latex-cheat-sheet/). - * For units of measure, use metric or imperial but be consistent. - -### Headings -Headings should not contain inline code font or style formatting such as bold, italic, or code font. -Headings should always immediately precede body text. Do not follow a heading with an admonition or another heading without some form of introductory or descriptive text. - -### Lists -Typically, we use numbered lists and bulleted lists. List items are sentence-capped. List items should be treated as separate items and should not be strung together with punctuation or conjunctions. - -NOT style: - -* Here is an item, and -* here is another item; and -* here is the final item. - -Style: - -* Here is an item -* Here is another item -* Here is the final item - -Or: - -1. Here is an item -2. Here is another item -3. Here is the final item - -### Punctuation - * **Abbreviation**: spell out all words on first mention. European Union (EU) and then EU. Do not use full points / periods or spaces between initials: BBC, PhD, mph, 4am, etc. - * **Ampersand**: generally speaking, do not use an ampersand in place of the word "and" unless referring to a company or publication that uses it: P&O, *Past & Present*. - * **Apostrophe**: use the possessive 's after singular words or names that end in s – St James's, Jones's, mistress's; use it after plurals that do not end in s: children's, people’s, media's. - * **Brackets / Parentheses**: it is better to use commas or dashes. Use round brackets to introduce explanatory material into a direct quote, eg: He said: "When finished it (the tunnel) will revolutionise travel" or "She said adiós (goodbye)". Place a full stop / period outside a closing bracket if the material inside is not a sentence (like this). (But an independent sentence takes the full stop before the closing bracket.) - * **Colon**: use to introduce lists, tabulations, texts, as in: - * The committee recommends: extending licensing hours to midnight; allowing children on licensed premises; relaxing planning controls on new public houses. - * Use after the name of a speaker for a whole quoted sentence: Mr James Sherwood, chairman of Sealink, said: "We have..." - * Lowercase the first letter after a colon: this is how we do it. - * **Comma**: serial comma (this, that, and the other). - * **Dash**: a useful device to use instead of commas, but not more than one pair per sentence. - * **Ellipsis**: three periods separated from the preceding and following words by a space ( ... ). Use to condense a direct quote (thus the quote "the people sitting in this meeting room deserve a better deal" becomes "the people ... deserve a better deal"). - * **Exclamation Mark**: use only at the end of a direct quote when it is clear that the remark is exclamatory, eg "I hate intolerance!" - * **Full Stop / Period**: use frequently. Sentences should be short, crisp, straightforward. But do not put full stops between initials, after status title (Mx, Dr) or between abbreviations (EU). - * **Hyphen**: use to avoid ambiguity or to form a single idea from two or more words: - * Fractions: two-thirds. - * Most words that begin with anti, non and neo. - * A sum followed by the word worth - £10 million-worth of exports. - * Some titles (director-general, secretary-general, but Attorney General, general secretary etc). The rule is to adopt the usage of the authority which created it - * Avoiding ambiguity (little-used car ... little used car). - * Compass quarters (south-west, north-east). - * **Quotation Marks**: use straight (not curly) quotation marks for direct quotes. Use either single or double quotation marks but be consistent. - -### Capitalisation -The guideline is to use them sparingly in the running prose. Specific rules: - -* **Title Case**: headings and book titles should use title case: "Preparing the Data for Analysis"; *The Pride and the Passion*, etc. -* **Always Capitalized**: - * **Proper Names**: William J. Turkel – unless the person choses to spell their name otherwise (eg "bell hooks"). - * **Artistic, Cultural, Government Organizations, etc**: Museum of the Moving Image, Anne Frank House, Home Office, Agency for Global Media, United Nations. - * **Holidays and Festivals**: Diwali, Hanukkah, Eid-Ul-Adha, Ramadan. -* **Sometimes or Partially Capitalized**: - * **Places**: capitals for countries, regions, recognisable areas (eg, the Middle East, Senegal). Lower case for points of the compass, except where they are used as part of a place name (to reach the North Pole, head north). Further examples include: north-east Kenya, south Brazil, the west, western Canada, the far east, south-east Asia, Central America, Latin America. - * **Historic Events**: first world war, second world war; Crimean/Boer/Vietnam/Gulf war; hundred years war. - * **Religion**: Upper case for Anglican, Baptist, Buddhist, Catholic, Christian, Hindu, Methodist, Muslim, Protestant, Roman Catholic, Sikh, but lower for evangelicals, charismatics, atheists. - * **Holy Books (select)**: - * **Bible**: Capitalise if referring to Old or New Testament. - * **Buddhist**: sutras (sermons) and abhidhamma (analysis and interpretation). For Tibetan Buddhism there are also tantric texts and the Tibetan Book of the Dead. - * **Hindu**: the Śruti texts: Vedas, Samhitas, Brahmanas, Aranyakas, Upanishads; the Vedāngas, Hindu epics, Sutras, Shastras, philosophical texts, the Puranas, the Kāvya, the Bhasyas, many Nibandhas. - * **Judaism**: the Tanakh (Torah, Nevi'im, Ketuvim), Talmud (Mishnah, Gemara) - * **Qu'ran**: Capitalise. Texts include the Hadith, the Tawrat (Torah), Zabur (possibly Psalms), Injil (1.2 billion). - * **Sikh**: Adi Granth (commonly called the Guru Granth Sahib), the Dasam Granth, the Varan Bhai Gurdas, the texts of Bhai Nand Lal. - * **Jobs**: Capitalise the title when used with the name – President Macron but not as a description – Emmanuel Macron, president of France. The Pope and the Queen have capital letters. - * **Organisations and Institutions**: the Government (cap in all references), the Cabinet (cap in all references), the Church of Ireland ("the church"), the Department of Education and Science ("the department"), Western University ("the university"), the Court of Appeal ("the appeal court" or "the court"). - * **Universities and Colleges**: Capitals for institution, lower case for departments ("Australian National University department of medieval history"). - * **Religious Institutions, Hospitals and Schools**: cap up the proper or place name, lower case the rest eg Nurture Hillandale rehabilitation hospital, Vernon county primary school, Ali Pasha’s mosque. -* **Always Lowercase**: - * **Committees, Reports and Inquiries**: committee on climate change, trade and industry committee, royal commission on electoral reform - * **Agencies, Commissions, Public Bodies, Quangos**: benefits agency, crown prosecution service, customs and excise, parole board - * **Seasons**: spring, summer, autumn/fall, winter. - * **Currencies**: euro, franc, mark, sterling, dong etc - -### References -* Links rather than endnotes may be appropriate in most cases. -* Ensure linked phrases are semantically meaningful. Do not link terms that are meaningful only to sighted users such as "click here". -* All traditionally published and academic literature should be end-noted rather than linked. -* If you are writing an "analysis" tutorial, you must refer to published scholarly literature. -* Endnote superscripts should be outside the final punctuation like this.² Not inside like this². -* Use the "Notes and Bibliography" system found in the [*The Chicago Manual of Style*, 17th Edition](https://www.chicagomanualofstyle.org/tools_citationguide/citation-guide-1.html) for endnotes. -* On first mention of a published work, include author name (including first/given name). For example, "You can find more information in *The Elements of Typographic Style* by Robert Bringhurst," or "For more information, consult Robert Bringhurt’s *The Elements of Typographic Style*." On subsequent references, just use the book title. Author’s names can be shortened to surname only on subsequent use. -* Endnotes should not just contain a URL. - * (Correct): Grove, John. "Calhoun and Conservative Reform." *American Political Thought* 4, no. 2 (2015): 203–27. https://doi.org/10.1086/680389. - * (Incorrect): https://doi.org/10.1086/680389 -* To cite software according to [the recommendations of Software Heritage](https://www.softwareheritage.org/save-and-reference-research-software/), please provide available elements of the following information: author, title, version, year of release, license, repository URL. Below you will find an example following the _Chicago Manual, 17th edition_ citation style: - * **End note**: Julien Barnier _et al._. _Scatterd3_, version 1.0.1 (2021). GPL. [https://cran.r-project.org/web/packages/scatterD3/index.html](https://cran.r-project.org/web/packages/scatterD3/index.html). - * **Bibliography entry**: Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. [https://cran.r-project.org/web/packages/scatterD3/index.html](https://cran.r-project.org/web/packages/scatterD3/index.html). - - -### Challenging Words Explained - - * **Collective Nouns** (group, family, cabinet, etc) take singular or plural verb according to meaning: the family was shocked, the family were sitting down, scratching their heads. - * **Less or Fewer?** Less means less in quantity, (less money); fewer means smaller in number, (fewer coins). - * **Over or More Than?** Over and under answer the question "how much?"; more than and fewer than answer the question "how many?": she is over 18, there were more than 20,000 at the game. - * **That or Which?** that defines, which informs: this is the house that Jack built, but this house, which Jack built, is now falling down. - -## C. Formatting Guidelines -This final section covers matters of formatting for submission. Read this section before and after writing your draft. If you get any of these elements wrong, you will be able to correct them when we post a live preview of your lesson at the start of the peer review process. - -### Write in Markdown -All lessons must be written in [Markdown](https://en.wikipedia.org/wiki/Markdown). A template for writing your lessons has been provided. - -* [Download the English Language Lesson template (.md)]({{site.baseurl}}/en/lesson-template.md). - -Markdown is a mark-up language that is best created with a text editor. MS Word and Open Office are NOT text editors and should be avoided. We recommend [Atom](https://atom.io/), [TextWrangler](https://www.barebones.com/products/textwrangler/), [TextEdit](https://en.wikipedia.org/wiki/TextEdit), [MacDown](https://macdown.uranusjr.com/) or [Notepad++](https://notepad-plus-plus.org/download). -For a gentle introduction to Markdown formatting see [Getting Started with Markdown]({{site.baseurl}}/en/lessons/getting-started-with-markdown), or the concise reference [GitHub Guide to Markdown](https://guides.github.com/features/mastering-markdown/). - -Your lesson should be saved in .md format. Your lesson filename becomes part of the lesson URL. Therefore, it should be named according to the following rules: - - * A short, lowercase, descriptive name that gives a clear indication of the lesson contents (eg. getting-started-with-markdown.md). - * Do not use spaces or underscores in the filename; use hyphens instead. - * Use a keyword-rich filename that includes key technologies or methods (eg, Python or Sentiment Analysis). - -### Bold, Italics, and Underline -To ensure consistency across lessons, adhere to the following text formatting guidelines: - -#### Bold - * Bold is not used except in exceptional circumstances. - * Bold is formatted using **\*\*double asterisks\*\***. - -#### Italics - * Use italics for book titles, films, TV programmes, paintings, songs, albums, and websites. - * Never use italics for business names (the *Facebook* website is owned by Facebook). - * Do not use italics in headlines, even if referring to a book title. - * Italics are formatted using *\*single asterisks\**. - -#### Underline - * Underline is not used. - - -### Alerts and Warnings -If you want to include an aside or a warning to readers, you can set it apart from the main text: - -``` -
- Be sure that you follow directions carefully! -
-``` - -### Figures and Images -Images can help readers understand your lesson steps, but should not be used for decoration. If you wish to use images in your lesson, label them sequentially LESSON-NAME1.jpg, LESSON-NAME2.jpg, etc. Refer to them in the text as "Figure 1", "Figure 2", and so on. All figures must come with a concise figure caption, descriptive alt-text, and endnotes where appropriate. You must have the legal right to post any images. - -Use web-friendly file formats such as .png or .jpg and reduce large images to a maximum of 840px on the longest side. This is important for readers in countries with slower internet speeds. - -Images should be saved in a folder with the same name as your lesson .md file. The editor assigned to your lesson can assist you in uploading your images when you submit. - -To insert an image in your text, use the following format: - -{% raw %} -``` markdown -{% include figure.html filename="IMAGE-FILENAME" alt="Visual description of figure image" caption="YOUR CAPTION USING \"ESCAPED\" QUOTES" %} -``` -{% endraw %} - -Note that internal quotation marks in your caption must be escaped with a backslash, as in the example above. Images may not appear in previews of your lesson, but your editor will ensure they render properly when the lesson is published. - -### Code Examples -Lines of code should be formatted to distinguish them clearly from prose: - - * Lines of code should be maximum 80 characters - * Multi-line code blocks should be enclosed in three \`\`\`back-ticks\`\`\`. - * Inline code (rarely used) can be enclosed in single \`backticks\`. - - -``` -They will look like this -``` -`and this` respectively. - --- -Follow best practice in writing your code: - -* **Variable and Function Names**: variable names should be nouns (eg "counter") and function names should be verbs (eg "createFile"). Choose names that are concise and meaningful. You may use [snake_case](https://en.wikipedia.org/wiki/Snake_case) or [camelCase](https://en.wikipedia.org/wiki/Camel_case), but be consistent. -* **User Commands**: when writing about text you want the reader to replace with their own information, use FULL CAPS and enclose by ` backticks ` (eg, \`USERNAME HERE\`). -* **Filenames**: filenames that you ask your reader to create or use should be enclosed in `backticks` when mentioned in the text and should include their file extension. Choose names that are concise and meaningful. You may use [snake_case](https://en.wikipedia.org/wiki/Snake_case) or [camelCase](https://en.wikipedia.org/wiki/Camel_case), but be consistent (eg, `data.txt`, `cleanData.py` etc). -* **Reserved Words**: words that are part of a programming language should always be formatted as `code` using `back-ticks` in the running prose. A list of reserved words in common programming languages include: - -#### JavaScript: - -`abstract`, `arguments`, `await`, `Boolean`, `break`, `byte`, `case`, `catch`, `char`, `class`, `const`, `continue`, `debugger`, `default`, `delete`, `do`, `double`, `else`, `enum`, `eval`, `export`, `extends`, `false`, `final`, `finally`, `float`, `for`, `function`, `goto`, `if`, `implements`, `import`, `in`, `instanceof`, `int`, `interface`, `let`, `long`, `native`, `new`, `null`, `package`, `private`, `protected`, `public`, `return`, `short`, `static`, `super`, `switch`, `synchronized`, `this`, `throw`, `throws`, `transient`, `true`, `try`, `typeof`, `var`, `void`, `volatile`, `while`, `with`, `yield`. - -#### Python 2: -`and`, `as`, `assert`, `break`, `class`, `continue`, `def`, `del`, `elif`, `else`, `except`, `exec`, `finally`, `for`, `from`, `global`, `if`, `import`, `in`, `is`, `lambda`, `not`, `or`, `pass`, `print`, `raise`, `return`, `try`, `while`, `with`, `yield`. - -#### Python 3: -`and`, `as`, `assert`, `break`, `class`, `continue`, `def`, `del`, `elif`, `else`, `except`, `False`, `finally`, `for`, `from`, `global`, `if`, `import`, `in`, `is`, `lambda`, `nonlocal`, `None`, `not`, `or`, `pass`, `raise`, `return`, `True`, `try`, `while`, `with`, `yield`. - -#### R: -`break`, `else`, `for`, `FALSE`, `function`, `if`, `in`, `Inf`, `NA`, `NA_character_`, `NA_complex_`, `NA_integer_`, `NA_real_`, `NaN`, `next`, `NULL`, `repeat`, `TRUE`, `while`. - - -## Step 3: Submitting a New Lesson - -Double-check that your lesson file has been prepared to the above specifications. Once you are satisfied, we strongly recommend that you ask at least two people to try your tutorial and provide feedback. This will help you make improvements that mean our peer reviewers can focus on helping you produce the strongest possible lesson. - -You are ready to submit the lesson for peer review. Submissions are made by emailing materials to your editor so they can upload them to our peer review site on [Github](https://github.com/programminghistorian/ph-submissions/). - -1. **Getting Access**: create a [free Github account](https://github.com/join). Email your Github username to your editor who will give you upload access to our submission site. Let the editor know the file name of your lesson and if you have any images or data files accompanying your tutorial. You will not do the initial upload to GitHub, but you will need access to post subsequent revisions. -2. **Prepare your materials**: if your lesson includes images, make sure all of the files are named according to the naming conventions specified above.These images should be submitted in a single, compressed folder. If your lesson includes data files, they should be submitted in another compressed folder. -3. **Email your editor**: let your editor know that you are ready to submit your lesson. This email should include the lesson file as well as the image and assets folders if applicable. -4. **Join the conversation**: the editor will upload your files to our [submissions repository](https://github.com/programminghistorian/ph-submissions) and make any necessary, initial changes to them. They will also open a review ticket for your lesson. -5. **Make revisions**: the initial lesson upload will be carried out by your assigned editor, but the editorial process will require that you make further changes. All subsequent revisions should be made by the author directly to the files in our submissions repository to ensure you are working from the latest version of the lesson file. - -## The Peer Review Process - -Your editor will check that your files have been uploaded and formatted properly. At this stage you will be sent a preview link where any formatting errors will be evident and you can fix them. - -The peer review will be recorded on a Github "[ticket](https://github.com/programminghistorian/ph-submissions/issues)", which acts like an open message board discussion. Be aware that our peer review happens in public and remains publicly available as a permanent record of peer review. If you have concerns or would like to request a closed review, contact your assigned editor. - -The peer review process normally happens in 3 stages: - -1) The editor assigned to your lesson will carefully read and try your lesson, providing a first round of feedback that you will be asked to respond to. The purpose of this first round of feedback is to ensure that your lesson addresses the needs of *Programming Historian* readers, and to make sure that the external peer reviewers receive a lesson that works. You will normally be given one month to respond to this first peer review. - -2) The editor will then open the lesson for formal peer review. This will include at least two reviewers invited by the editor, and may also include comments from the wider community, who are welcome to contribute views. We generally try to ask reviewers to provide their comments within one month, but sometimes unforeseen circumstances mean this is not possible. The editor should make it clear to you that you should not respond to reviews until after both reviews have been published and the editor has summarised and provided clear instructions for moving forward. In some cases this may be a suggestion to substantially revise or rethink the lesson. In other cases it will be a matter of making some changes. Depending on the peer review comments, and the nature of issues raised, you may need to revise the tutorial more than once, but the editor will endeavour to ensure that you are given a clear pathway towards publication. You always have the option of withdrawing from the review process if you so choose. - -3) Once your editor and peer reviewers are happy with the piece, the editor will recommend publication to the Managing Editor, who will read the piece to ensure that it meets our Author's Guidelines and standards. In some cases there may be additional revisions or copy editing at this stage to bring the piece in line with our publishing standards. If the Managing Editor is happy with the piece, it will be moved to the live site for publication. Your editor will inform you of any additional information required at this stage. - -You may find it helpful to read our [editor guidelines](/editor-guidelines), which detail our editorial process. - -If at any point you are unsure of your role or what to do next, post a question to the peer review issue. One of our editors will respond as soon as possible. We endeavour to respond to all queries within a few days. - -### What happens after your lesson is published? - -Occasionally, we receive feedback from users who have encountered an error while completing one of our lessons. If this happens, our Publishing Assistant will open an Issue on GitHub, then carry out an assessment to confirm whether the error reported represents a problem caused by the user (editing the lesson's code or changing its dataset, for example) or a problem within the lesson itself. If the latter, our Publishing Assistant will re-test the relevant part(s) of the lesson and undertake research to identify a fix. As part of this Lesson Maintenance process, we may contact you alongside other members of the *Programming Historian* team to ask for advice. In the case that no fix can be found, we will propose adding a warning to the lesson explaining that some users may encounter an error. Where possible, the warning should include links to further reading, empowering users to identify a solution themselves. - -### Holding Us to Account - -Our team of volunteers works hard to provide a rigourous, collegial, and efficient peer review for authors. However, we recognize that there are times when we may fall short of expectations. We want authors to feel empowered to hold us to high standards. If, for whatever reason, you feel that you have been treated unfairly, that you are unhappy or confused by the process, that the review process has been unnecessarily delayed, that a reviewer has been rude, that your editor has not been responsive enough, or have any other concern, please bring it to our attention so we can address it proactively. - -Raising a concern will NOT negatively affect the outcome of your peer review - even a peer review in progress. - -To raise a concern, please contact one of the following parties, chosing whomever you feel most comfortable approaching. - -* Your assigned editor -* The managing editor -* Our independent ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca) - -We hope you don't find yourself in a situation in which you are unhappy, but if you do, we thank you for helping us to improve. - ---- - -This style guide was created with support from the School of Humanities, University of Hertfordshire. diff --git a/en/contribute.md b/en/contribute.md index 1e3cc5431..e10a69076 100755 --- a/en/contribute.md +++ b/en/contribute.md @@ -11,27 +11,27 @@ The _Programming Historian_ runs on the far-from-endless energy of volunteers, a ## Write a new lesson
-Our English journal will open its next annual submission window in October 2025. In the meantime, you may find it useful to consult our past call for proposals (closed in January 2025). Submissions to our Spanish, French and Portuguese journals are open year-round. +Our English journal will open its next annual submission window in November 2025. In the meantime, you may find it useful to consult our past call for proposals (closed in January 2025). Submissions to our Spanish, French and Portuguese journals are open year-round.
{{ site.data.snippets.write-a-lesson-image-alt[page.lang] }} Writing a tutorial is one of the best ways to teach yourself particular skills and actively engage in the digital humanities community. -We don't simply accept or reject articles like traditional journals. Our editors collaborate with you to help craft your essay to be as clear and as useful as possible--a great way to improve your technical writing skills. Please read more about our [submission process]({{site.baseurl}}/en/author-guidelines). +We don't simply accept or reject articles like traditional journals. Our editors collaborate with you to help craft your essay to be as clear and as useful as possible--a great way to improve your technical writing skills. Please read more about our [Lesson Framework]({{site.baseurl}}/en/lesson-framework). ## Review a lesson We are proud to use an Open Peer Review system. We think this provides a valuable opportunity for collaboration between authors, translators and peers in the global community. The peer review process also supports productive knowledge exchange, and helps us to shape lessons that are practical, accessible, and sustainable. -If you would like to contribute as a peer reviewer, please take a few minutes to [register your interest via our Google Form](https://tinyurl.com/en-ph-peer-review) which you can submit directly online. There's also [a plain-text version](/assets/forms/en-ph-peer-review-form.txt) which you can [send to us by email](mailto:publishing.assistant@programminghistorian.org), if you prefer. We seek volunteers who are available to review a lesson within 12 months of registering their interest. +If you would like to contribute as a peer reviewer, please take a few minutes to [register your interest via our Google Form](https://tinyurl.com/en-ph-peer-review) which you can submit directly online. There's also [a plain-text version](/assets/forms/en-ph-peer-review-form.txt) which you can [send to us by email](mailto:admin@programminghistorian.org), if you prefer. We seek volunteers who are available to review a lesson within 12 months of registering their interest. ## Edit lessons {{ site.data.snippets.editor-guidelines-image-alt[page.lang] }} -Our editorial board members help facilitate peer review and work with authors closely to make improvements to their lessons. Our [guidelines for editors](editor-guidelines) is meant to ensure that everyone, from authors to reviewers to members of the wider community, receive a fair and consistent experience during peer review. +Our editorial board members help facilitate peer review and work with authors closely to make improvements to their lessons. Our [publishing workflow](publishing-workflow) is meant to ensure that everyone, from authors to reviewers to members of the wider community, receive a fair and consistent experience during peer review. From time to time we may advertise that we are seeking more editors. diff --git a/en/editor-guidelines.md b/en/editor-guidelines.md deleted file mode 100755 index a5bbc61ff..000000000 --- a/en/editor-guidelines.md +++ /dev/null @@ -1,426 +0,0 @@ ---- -title: Editor Guidelines -layout: blank -redirect_from: /editor-guidelines ---- - -# Editor Guidelines - -This page contains step-by-step instructions for editors facilitating peer review for the *Programming Historian*. - - -## The Role of the Editor -Thank you for editing a lesson for the *Programming Historian*. We are extremely grateful for your efforts. This guide is meant to ensure that all authors, editors, and reviewers receive a consistent and fair experience with the *Programming Historian*. If you have any questions about anything in these guidelines, please email one of the other editors or post a question on our [Github issues](https://github.com/programminghistorian/jekyll/issues). Do the same if you think these guidelines need improvement or updating. - -{% include toc.html %} - - - - - - -We always encourage prospective authors to pitch their ideas before they start writing. If a piece is not suitable for the *Programming Historian* our job is to tell an author before they have written a full tutorial. We hope this saves everyone time and energy. Once we have spoken to an author and encouraged their idea, our aim is always to support authors until the piece is publishable. Our goal is to help them reach that stage as efficiently as possible with clear guidance. You may find it helpful to familiarise yourself with our [instructions for authors](/author-guidelines). - -### Safe Spaces -The *Programming Historian* is committed to providing a safe space for the exchange of ideas, where everyone can share without fear of harassment or abuse. The editor plays a fundamental role in ensuring that space endures. Your job includes enforcing our anti-harassment policy at all times. If you need help please ask one of the other editors or PH ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca). You can read more about our [commitment to safe spaces](/posts/PH-commitment-to-diversity) 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 correspondence between reviewers, authors, editors, and contributors to our public forums. - -The *Programming Historian* is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutize ideas, to ask questions, make suggestions, or to requests for 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. - -### Track Proposed Lessons -Once a lesson proposal has been given the "green light" by the editorial team and has been assigned an editor, the editor will work with the author to clarify the goals of the lesson and to establish an agreed upon submission deadline. The recommended time frame is 90 days from the start of the editorial conversation, though this can be adjusted if needed. - -The editor will then create a "Proposed Lesson" issue in the [submissions repository on Github](https://github.com/programminghistorian/ph-submissions/issues) and assign it the "proposals" label. The default proposal text is included in the issue template, or can be copied from below. - -``` -The Programming Historian has received the following proposal for a lesson on 'PROVISIONAL LESSON TITLE' by AUTHOR(S) NAME(S). The proposed learning outcomes of the lesson are: - -- key learning outcome 1 -- key learning outcome 2 -- key learning outcome 3 (add as needed) - -In order to promote speedy publication of this important topic, we have agreed to a submission date of no later than [90 DAYS BY DEFAULT BY LONGER IF AGREED WITH EDITOR]. The author(s) agree to contact the editor in advance if they need to revise the deadline. - -If the lesson is not submitted by [THE AGREED DATE], the editor will attempt to contact the author(s). If they do not receive an update, this ticket will be closed. The ticket can be reopened at a future date at the request of the author(s). - -The main editorial contact for this lesson is [EDITOR USERNAME]. If there are any concerns from the authors they can contact the Ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca). -``` - -The editor is encouraged to adjust the issue text to reflect any additional goals or requirements agreed upon between the author(s) and editor. - -When the lesson materials are ready for submission, the author will contact their assigned editor, whose job will be to upload them to the [ph-submissions repository](https://github.com/programminghistorian/ph-submissions) after first checking to ensure that there are no major metadata issues. - -1. **Uploading the Lesson**: the lesson itself should be uploaded to the appropriate subfolder (depending on whether it is an original lesson or a translation) of the [lessons folder](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/en) within the corresponding language folder in the root of the ph-submissions repository. If you need help, see [GitHub's instructions](https://help.github.com/articles/adding-a-file-to-a-repository/). -2. **Uploading Images**: if the lesson includes images, make sure all of the files are named according to the naming conventions specified in the [author guidelines](/author-guidelines). The editor should create a folder for the images in the [images directory](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/images). This folder should have the same name as the lesson filename. Upload the images to this folder. -3. **Uploading Data**: if the lesson includes data files, they should be uploaded to a similarly named folder in the [assets directory](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/assets). - -After uploading, the editor should check the [commit history for the repository](https://github.com/programminghistorian/ph-submissions/commits/gh-pages) to ensure that their upload received a green check mark. If not, something went wrong and the [wiki](https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions#checking-travis-for-errors) should be consulted for troubleshooting the errors. Upon successful submission of the lesson, the editor will create a review ticket for the lesson and close the proposal issue. From here on, the editor should ensure that the author work from the latest version of the lesson in the repository and upload changes directly to GitHub themselves. - -### Open Peer Review -The *Programming Historian* uses a model of open peer review, while we believe this helps maintain civility and the productive sharing of ideas, authors have the right (and we have a requirement to respect that right) to request a closed peer review. There are many reasons why someone might be hesitant to engage in an open review and we encourage authors to always pursue the option with which they are most comfortable. - -Before soliciting external reviews, the editor should read and try the tutorial and use their experience with the *Programming Historian* to help the author make initial improvements (if required). The editor is not expected to be a expert in content of the lesson, this is the role of the [reviewers](/reviewer-guidelines). - -The editor should complete an initial sustainability overview of the submission to ensure that software versions and dependencies are clearly marked, specificities of software like screenshots are limited to those required to complete the lesson, and that the lesson makes use of existing software documentation whenever available and appropriate. Editors should also ensure that lessons try, as much as possible, to avoid software specific directions, such as "Right-click on the _x_ icon to access the _x_ menu," instead favoring general methodological overviews. The Editorial Checklist [contains more details about sustainability practices](#c-sustainability-review) for PH. - -Often editors need help clarifying the intended audience of a lesson, or identifying jargon that needs further explanation. This initial review helps let the external reviewers focus on improving the piece. This is normally done openly on our submission system (see below), but it can be a closed review at the request of either party. - -Once an author has revised the tutorial to the satisfaction of the editor, it is the editor's job to invite two formal external peer reviews. In the interest of our [commitment to diversity](https://github.com/programminghistorian/jekyll/issues), we encourage editors to ask themselves if they have made a sufficient effort to draw from reviewers who are distinct from themselves either by gender, nationality, race, age, or academic background. Please try not to find two people who are very like you. - -To coordinate our requests for reviewers, please use the "Programming Historian - Reviewer Tracking" Google Spreadsheet. (Contact the managing editor if you need help accessing the spreadsheet.) Prior to sending a review request, check the list to make sure that the person has not been recently contacted by another editor. To avoid over-taxing reviewers, please limit requests to once a year. If a reviewer has been contacted in the past year, the "date_contacted" field will display as red. - -For each potential reviewer you do contact, regardless of response, please enter: - -+ the date contacted, -+ the reviewer's name, -+ your name as the editor, -+ the lesson to be reviewed, -+ the response, -+ and, if the response was "yes," the date completed. - -Please enter the date using the `mm/dd/yyyy` format. - -When inviting reviewers, the editor should provide them with our [reviewer guidelines](/reviewer-guidelines) and give them a deadline for completing their review (usually one month) so that we can ensure the timely publication of the tutorial. - -When a lesson has been submitted, the editor will open a new 'issue' on our [Github submissions repository](https://github.com/programminghistorian/ph-submissions/issues) where the open review will take place. This message board allows everyone to keep track of the conversation. You will need to sign up for a free Github account if you do not already have one, as will both the author and reviewers. - -### The Initial Comment - -Your first comment on the message board for a given tutorial review should use our template which outlines the role of the editor and what will take place during the review, as well as everyone's options in the unlikely event that something goes wrong. Please adapt [the template](https://github.com/programminghistorian/ph-submissions/blob/gh-pages/.github/ISSUE_TEMPLATE), which should appear automatically in all new issue boxes, as needed: - -``` -The Programming Historian has received the following tutorial on '[LESSON TITLE]' by [AUTHOR GITHUB USERNAME]. This lesson is now under review and can be read at: - -http://programminghistorian.github.io/ph-submissions/en/["lessons" or "translations"]/[URL to lesson] - -I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded. - -Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred. - -I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to our ombudsperson (Dr Ian Milligan - i2milligan@uwaterloo.ca) if you feel there's a need for an ombudsperson to step in. - -Anti-Harassment Policy -_ - -This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums. - -The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for 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. -``` - -### Guiding the Conversation - -Everyone will be looking to you as the editor for guidance on the system. For most authors and reviewers this will be their first experience with our peer review process. The immediate feedback offered by the message board means that authors may see the reviewer comments before you do. That means you will have to clearly signpost how everything will work and when everyone should participate or wait for further instruction. - -If possible it is always best to acknowledge review milestones as soon as possible. For example, after the first review has come in, post a response to thank the reviewer and let the author know that another review is on its way. Suggest that they wait for the second review before responding. This lets everyone know what to expect. - -If you are really busy, if possible make a note on the forum to say you have seen the new activity, but will need some time to respond properly. Managing expectations can be key to keeping everyone happy. - -### Summarising the Review - -Once the two formal reviews are in (as well as any informal contributions from the community), you will have to summarise the suggestions and give the author a clear path for any revisions that you would like them to respond to. If any suggestions are counter to our aims at the *Programming Historian*, politely tell the author to forego those suggestions. Keep in mind what it is like to be an author and receive a review. You want clear guidance, but also the right to reject ideas that don't improve the piece. You also want assurance that you are not trying to hit a moving target. A good summary of reviews means an author can respond and expect publication if all significant obstacles are met. - -### Managing the Revision Process - -With your summary of the reviews and any final instructions for the editor, include a reminder to the author that revisions should be completed within 4 weeks. This is to ensure that lessons are published in a timely fashion and do not drag on unnecessarily. If the author anticipates trouble meeting the deadline, they should contact their editor to establish a more suitable due date. - -## Technical Processes of Review - Editorial Checklist - -Our peer review is conducted on our [Submissions repository](https://github.com/programminghistorian/ph-submissions) on Github. Full instructions for how to upload files, including file formats and formatting guidelines can be found on our [Author Submission Instructions](/author-guidelines) which will always contain the most up to date instructions. Please familiarise yourself with these steps or refer to them as needed. If you need help you are always welcome to [email another editor directly](/project-team). - -There are a few areas where you should intervene in the process from a technical standpoint. They include: - -### A) Naming the Lesson File - -The **Editor** should suggest a name for the new lesson file that conforms to these guidelines: - -- Make the filename short, but descriptive; this filename will eventually become the slug for the lesson's URL when published. -- A good URL would fit nicely on a powerpoint slide, is easy to remember, and tells you something about the lesson. Our URLS take the following format: `https://programminghistorian.org/en/lessons/FILENAME-HERE` -- Do not put spaces in the filename; use hyphens instead. -- The filename extension should be `.md` so that GitHub will generate a preview of the lesson. - -Once you have chosen a name for the lesson file, use the same name to create a new folder in `images` which will contain all of the images for the lesson. If the lesson uses data files, do the same in the `assets` folder. - -### B) Initial Check of Markdown - -Authors are responsible for checking that their lesson has rendered properly in Markdown. If they have followed the syntax rules, it should be ok. If you can see any Markdown symbols on the page, something went wrong. Detailed instructions of Markdown syntax are available on our [Author Guidelines](/author-guidelines) - -You can quickly check that everything looks correct on a lesson submission by looking at the rendered version of the page. It will be found at: - -`http://programminghistorian.github.io/ph-submissions/en/lessons/FILENAME-HERE` (note - no .md at the end) - -Note that if it is a translation you would substitute "translations" for "lessons". If that doesn't work, let the technical team know, and they will try to diagnose it. - -### C) Sustainability & Internationalization Review -To increase the lifespan of our lessons, _Programming Historian_ editors should complete a sustainability review as a part of their final checklist. Every submission is different and some of these areas may not be applicable to all submissions. Keeping in mind the difficulty level of each lesson and its intended audience, editors should use these areas as guidelines to ensure that lessons are as sustainable as possible from the date of publication. - -- All software versions and dependencies are described in the introduction to the lesson -- Sources of data for lessons are clearly noted and should be hosted at the _Programming Historian_ whenever possible -- Lessons make use of existing software documentation whenever possible -- Lessons link to Wikipedia for technical terminology -- Screenshots of software GUIs are limited to those that are required to understand the lesson -- External links (e.g. software or data sources) are current and live though authors should consider directing users to documentation generally rather than providing links to specific documentation pages -- Links to articles use DOIs if available - -To help reach a global audience, authors have been advised to adhere to the following guidelines where possible: - -- When choosing your methods or tools, try to make choices with multi-lingual readers in mind. This is particularly important when working on textual analysis methods, or where users may reasonably want to have support for different character sets (eg, accented characters, non-Latin, etc). -- When choosing primary sources, images, producing figures, or taking screen shots, consider how they will present themselves to a global audience. -- When writing, avoid jokes, cultural references, puns, plays on words, idiomatic expressions, sarcasm, emojis, or language that is more difficult than it needs to be. Mentions of persons, organisations, or historical details should always come with contextual information. It may help to assume your reader does not live in your country or speak your language. -- In code examples or metadata, use internationally recognised standard formats for dates and times ([ISO 8601:2004](https://www.iso.org/standard/40874.html)). In free text, be aware of cultural differences related to the representation of dates and times which might cause confusion. -- Where possible, choose methods and tools that have multi-lingual documentation. If this is not practical, it would be great if you could add some multi-lingual references at the end of your tutorial. - -Editors should work closely with authors to ensure that these criteria are met. Where this is not possible, justifications for not meeting them should be clearly and transparently outlined in the relevant review ticket - -### D) Verify Images - -All images should use consistent, semantically meaningful filenames that clearly indicate what they are. If a lesson has a large number of images in rapid succession, and the order is important (for example, a series of screenshots), it may be advisable to use a sequential naming system---ideally using the same hyphenated filename slug as the lesson itself (or an abbreviated version if the lesson title is rather long), followed by numbers to indicate which figure it is (For example, `counting-frequencies-1.png`, `counting-frequencies-2.png`, and so on.) - -If a lesson does use a sequential image naming system, it is possible that figure numbering will change during the peer review process. We ask that before a lesson is published that all filenames are updated to the proper figure numbers. This makes it much easier for us to update lessons if needed in the future. Thank you for helping us keep the *Programming Historian* sustainable. - -Regardless of how the images are named (semantically or sequentially), they should be placed in a subdirectory within the `images` directory. The subdirectory should be named using the same URL slug used to name the lesson. Make sure the images are in web-friendly formats such as PNG or JPEG and sized appropriately (both in terms of pixels and bytes). - -Full instructions on adding images is available in [Author Submission Instructions](/author-guidelines). - -### E) Verify Data files - -Similarly to Images, all data files should be stored on the site (not linked externally - for sustainability purposes). All data should be stored in the 'assets' directory, using the same rules as above, but authors should feel free to use a description for their data file that reflects what it is: - - - `/assets/LESSON-SLUG/Louvre-Paintings-1.csv` - - Occasionally, large assets used by particular lessons might be too large to be stored in our GitHub repository. If this is the case, we recommend that authors upload their assets to [Zenodo](https://zenodo.org/) for archiving and then provide the lesson editor with the DOI generated by Zenodo for linking from within the lesson. In the event that such datasets might already exist in an institutional repository, we still recommend uploading the version of the dataset used in *The Programming Historian* to Zenodo for the purposes of consistent use across all of our lessons. - - When uploading to Zenodo, all files (even if there is a single file) should be compressed into a single zip file. The zip file should have the same slug used for the lesson file. This is only necessary when the total size of the assets for the lesson is larger than 25MB. - -### F) Verify videos/gifs - -Videos and gifs are strongly discouraged because they create a range of problems. For example, it is difficult and time consuming to ask for changes to a video during the peer review process, and impossible for an editor to make minor updates to it in years to come as it becomes outdated. Videos also require the administration of a separate channel at YouTube. Videos also cannot be printed, and many of our readers use PDF copies or [printed copies of the *Programming Historian*](https://zenodo.org/record/49873#.V0lazGaGa7o). As such they should ONLY be used when absolutely necessary. - -If a tutorial contains a video it should be hosted on our YouTube channel (which is not set up yet so email the other editors when you get a video). A backup of the file should also be stored in our Github repository, following the same principles of naming and storage as in sections for images and data described above and stored in the 'assets' directory: - - - `/assets/LESSON-SLUG/FILENAME-HERE-3` - ---- - -## Recommend Publication - Editorial Checklist - -Once you and the author are happy with a tutorial, the next step is to recommend publication to the managing editor. This involves checking the files and adding some additional metadata before contacting them: - -### 1) Create an Author Bio - -If the lesson has been written by a new author, the managing editor will need to add a new bio for that person. You will need to provide the managing editor with a version of the following information: - -```yaml -- name: Jim Clifford - team: false - orcid: 0000-0000-1111-1111 - bio: - en: | - Jim Clifford is an assistant professor in the Department of History - at the University of Saskatchewan. -``` - -**Whitespace is important**, so be sure that the indentation matches the other examples. - -The `orcid` ID is optional, but highly encouraged if [authors have registered for an ID with the service](https://orcid.org/). **Only enter an ORCiD ID that an author has explicitly provided to you. Do enter an ID without first getting that author's confirmation that you are using the correct ID.** - -### 2) Add a table of contents to the lesson - -The following code should be added into the text of the lesson, usually before the first subheader: - -``` -{% raw %}{% include toc.html %}{% endraw %} -``` - -### 3) Add YAML metadata to the lesson file - -``` -title: "Your Title Here" -collection: lessons -layout: lesson -slug: e.g. introduction-to-sentiment-analysis -date: YYYY-MM-DD -translation_date: YYYY-MM-DD (translations only) -authors: -- Forename Surname -- Forename Surname etc -reviewers: -- Forename Surname -- Forename Surname etc -editors: -- Forename Surname -translator: -- Forename Surname (translations only) -translation-editor: -- Forename Surname (translations only) -translation-reviewer: -- Forename Surname (translations only) -original: slug to original published lesson (translations only) -review-ticket: e.g. https://github.com/programminghistorian/ph-submissions/issues/108 -difficulty: see guidance below -activity: ONE OF: acquiring, transforming, analyzing, presenting, sustaining -topics: - - topic one (see guidance below) - - topic two -abstract: | - see guidance below -avatar_alt: Description of lesson image -doi: Add DOI (see https://github.com/programminghistorian/jekyll/wiki/How-to-Request-a-new-DOI) -``` - -- **difficulty** To help readers evaluate which lessons best fit their goals and skill level, we provide "Recommended for ___ Users" information in the lesson YAML file. There are currently three tiers, which can be set with the following numerical codes: 1 (Beginning), 2 (Intermediate), 3 (Advanced). To add the difficulty level of 'intermediate' to the lesson, include the following in the YAML file: -``` -difficulty: 2 -``` -- **topics** can be any number of the things listed after "type:" in /\_data/topics.yml. You are also encouraged to create new topics that would help someone find the lesson. To do so, besides listing the topic(s) in the lesson's front matter, you should: -1. Add the topic to any existing lesson(s) also described by the new topic -2. Add the new topic(s) to /\_data/topics.yml following the format of the other topics there (note that topics can't have spaces—use hyphens if needed). -3. Edit /js/lessonfilter.js so the filter button to filter the lesson page to that topic works. Search the file for the ten-line chunk of code beginning with `$('#filter-api')`, copy and paste that chunk of code, and replace the *two* appearances of "api" with your new topic. -- **abstract** is a 1-3 sentence description of what you'll learn in the lesson. Try to avoid technical vocabulary when possible, as these summaries can help scholars without technical knowledge to try out something new. -- **slug** should have the path to the lesson on the public PH site, which means the hyphenated text following programminghistorian.org/lessons/ (e.g. building-static-sites-with-jekyll-github-pages)" -- **date** The date of the lesson should be updated to the date that the submission was moved to the main Jekyll repository. -- If the lesson uses formulas, you need to add `mathjax: true` for them to be displayed correctly. - -### 4) Find an Image to represent the lesson - -We represent our lessons using an old image that we feel captures some element of the task described in the tutorial. You can see the full range of these on the [main Lessons directory](/lessons/). These images are selected by editors. - -Here are a few places to look for lesson images: - - - The [British Library](https://www.flickr.com/photos/britishlibrary) - - The [Internet Archive Book Images](https://archive.org/details/bookimages) - - The [Virtual Manuscript Library of Switzerland](https://www.e-codices.unifr.ch/en) - - The [Library of Congress Maps](http://www.loc.gov/maps/collections) - -Ensure that the image matches the style of the other images (it should be a book image, not a photograph), is at least 200 pixels in both dimensions, and is not copyright restricted. Make sure the image is not offensive, and keeping with our [Commitment to Diversity](/posts/PH-commitment-to-diversity) try to find something that does not perpetuate stereotypes or send a subtle message about maleness and whiteness. - -Save the original image. The filename should be the same as the corresponding lesson’s URL slug with `-original` at the end, and the filetype must be `.png`. For example, the lesson “Cleaning Data with OpenRefine” has the URL slug `cleaning-data-with-openrefine`, so its original lesson image filename should be `cleaning-data-with-openrefine-original.png`. - -Then, create a new copy of the image. Crop it to a square without removing any important features. Change the dimensions to 200x200 pixels. Convert the image to grayscale. Perform any adjustments necessary to make it conform to the other lesson images, such as lightening or darkening it, or altering the contrast. Save this new image as the lesson’s URL slug; again, **the file format must be png**. In our previous example, the filename would be `cleaning-data-with-openrefine.png`. - -Upload the original image to the [gallery/originals](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/gallery/originals) folder, and upload the edited image to the [gallery](https://github.com/programminghistorian/ph-submissions/tree/gh-pages/gallery) folder. You will need to direct the managing editor to the locations of these images on the ph_submissions repo when you hand the files off to them for publishing. - -### 5) Inform the Managing Editor of your Recommendation to Publish - -The Managing Editor will read and carefully check over the lesson, ensuring that it adheres to our sustainability, internationalization, and style guidelines. If in the Managing Editor's discretion, the lesson fails to meet any of those thresholds of quality, it may be returned to the author for revision. If it passes these final quality control checks, the Managing Editor will publish the lesson by moving the files to the main website and check everything over. - -To make this person's job easier, post a list in the submission ticket of all files that need to be moved to publish the lesson. This should normally include: - -- The lesson .md file -- The directory for any accompanying files (images, data, etc) -- The gallery icons -- A bio if the author is new - -All except the bio should be represented as files somewhere in the ph_submissions repo. The bio can be placed in the ticket directly. - -### 6) Incorporate your lesson into our Twitter bot -In addition to the Twitter promotion outlined below, we also make use of a Twitter bot to regularly re-advertise older lessons. In order to add the new lesson to our pipeline, you need to add it as a row in [this spreadsheet](https://docs.google.com/spreadsheets/d/1o-C-3WwfcEYWipIFb112tkuM-XOI8pVVpA9_sag9Ph8/edit#gid=1625380994). Everyone on the editorial team should have the ability to make changes; email the google group if you have trouble. You will need to add a new row for your lesson to the end of the table with the following fields: - -* message_one (column A) - a twitter message to play early in the week. -* message_two (column B) - an "In Case You Missed It" twitter message to play later in the week. -* link (column C) - the link to the lesson. - -Leave column D blank and untouched - this field is used by the Twitter bot to log its progress through the list. Also note that this step should not replace your own promotion of the lesson. The bot goes through the lessons at random, one a week, so it could be months until your lesson comes up through this means. - -### 7) Thank Everyone and Encourage Promotion -Once you have been given word that the Managing Editor has successfully published the lesson, close the submission ticket, linking to the published lesson. It's important to send an email or message to everyone involved thanking them for their efforts. In particular, thank the author for contributing and encourage them to think of us again in future. It's also worth giving the author some ideas on promoting their lesson. The most-used lessons always have authors' energies behind them. For example authors should be encouraged to: - -- Tweet at least 3 times about their lesson (with 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 (eg, Wikipedia, community groups, etc). - -People don't find lessons on their own. The hard work is done, so let's make sure it was worth it! - -# Managing Editor Checklist - -The Managing Editor is responsible for carefully checking the lesson to make sure it adheres to all of our policies and requirements. If the lesson does not meet these requirements it should be referred back to the editor for further revision. This is a crucial part of the editorial workflow. Once the Managing Editor is satisfied that the lesson meets our standards, it is his/her role to move the files to the main website via a pull request. - -## 1) Carefully check the submission preview - -Check the submission preview for any errors or failures to meet our publication guidelines. Refer any issues back to the editor. - -## 2) Request DOI - -You need to request a new DOI for the lesson following the steps described in the [Wiki](https://github.com/programminghistorian/jekyll/wiki/How-to-Request-a-new-DOI). - -This part of the process should not take you more than one or two days, depending on the time difference you have with the UK (UTC). You can start next steps while you wait, but note that builds will initially fail until the DOI has been added to the lesson metadata. - -## 3) Move the Files - -The editor should have left you a clear list of files that need to be published on the submission ticket. If they have not done so, ask them to fix it before proceeding. - -There are several ways that you can perform a pull request to publish the files: - -* A) Follow our ["Making Technical Contributions" guidelines](https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions), which uses the Github website GUI. - -* B) Use `git` from the command line. The following instructions assume that you have already cloned both the `jekyll` and `ph-submissions` repositories to your local machine. (Our [lesson on using GitHub Desktop](/lessons/getting-started-with-github-desktop) may be helpful if this is new to you.) If you are not sure how to do that or have any questions, contact the technical team for assistance. - - 1. Go to the directory for your local `ph-submissions` repository. - 2. `git pull` to get all of the newest changes on your machine (or `sync` if you are using GitHub Desktop) - 3. Repeat Steps 1 and 2 for the `jekyll` repository on your local machine. - 4. Copy the lesson files and any related image and asset files from the `ph-submissions` directory on your machine to the appropriate places in the `jekyll` directory on your local machine. (You can use a command like `cp` on the Unix command line, or use your GUI file system if you are using GitHub Desktop.) - 5. From within the `jekyll` directory on your local machine, `git add` the new files and then `git commit` and `git push` the changes. - -After the lesson has been moved to the `jekyll` repository, you'll also need to archive the submitted lesson on the `ph-submissions` repository. - -1. Go to the directory for your local `ph-submissions` repository. -2. Add a new line to the YAML header of the now published lesson: `redirect_from: "/lessons/LESSON-SLUG"` -3. Move the now published lesson from `lessons/` into `lessons/published/`. -4. Move the image folder containing the images for the now published lesson from `images/` to `images/published/`. -5. Use `git add`, `git commit`, and `git push` to finalize all the changes (or follow the Making Technical Contributions instructions: https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions) - -## 4) Add the author bio to ph_authors.yml - -If the lesson has been written by a new author, the managing editor should add information about the author to the site's [authors directory](https://github.com/programminghistorian/jekyll/blob/gh-pages/_data/ph_authors.yml). Follow the syntax for the examples already included there, using the bio that the editor provided you: - -```yaml -- name: Jim Clifford - team: false - orcid: 0000-0000-1111-1111 - bio: - en: | - Jim Clifford is an assistant professor in the Department of History - at the University of Saskatchewan. -``` - -## 5) Confirm all links and YAML headers are functioning correctly - -Once you push your changes on to the `gh-pages` branch of the [programminghistorian][ph_repo] repository, the site will be automatically tested by [GitHub Actions]. -This test process checks three things: first, that all YAML and markdown code is parseable; second, that all the hyperlinks on the site point to valid, operational pages; and third, that internal links to pages on the _Programming Historian_ are all relative links that start with `/` rather than `https://programminghistorian.org/` - -[ph_repo]: https://github.com/programminghistorian/jekyll - -[GitHub Actions]: https://github.com/features/actions - -We run these builds primarily to check that URLs that _once_ were functional are _still_ functional, as often times external web pages are moved to new addresses, or are no longer live. -They are also an excellent way to catch small typos that may have evaded authors, editors, and reviewers. -The status of these tests (often called a "Build Status" on GitHub) can be seen by navigating to the [programminghistorian repository page][ph_repo], and clicking "Commits" on the upper left side of the code menu. - -![GitHub commit menu location](/images/website/editor-guidelines/gh_commits_location_screen.png) - -This will show you the list of every change made to the main repository, along with a status icon: - -- Green check mark: you're good to go! All the links on the page were checked and found valid. [**You may skip the rest of this section.**](#6-inform-the-editor) -- Yellow circle: your latest commit is still building. Wait 1-2 minutes and then check back. -- Red X: there was an error in the build. - -If your build has errored, you will need to consult the build logs to see what is causing it. - -1. Click on the red X for the most recent commit (the one nearest the top of the page), and click on the "Details" link. -![Travis details location](/images/website/editor-guidelines/commit_list_screen.png) -2. This will bring you to the build log page on GitHub Actions. Build logs are usually several hundred lines long, but the error information we are looking for will be at the bottom. Click on the small gray circle at the upper right of the log display to scroll to the bottom. -![The top of the Travis CI build screen](/images/website/editor-guidelines/travis_top_screen.png) -3. You may see two types of errors: first, if a page is missing a required YAML field (e.g. if a lesson does not have an `editors` field) then this will be marked in red. Failing links will be also be listed in red, grouped by the page they appeared in. If any links in your new lesson are causing errors, go back and double check that they do not have any typos. If they do, then make any necessary corrections and commit the changes to the repository, and wait for GitHub Actions to run its tests again. -![Locating error details in Travis CI build results](/images/website/editor-guidelines/travis_bottom_screen.png) - -- There are some rare circumstances in which a link will be failed by GitHub Actions, but will work perfectly fine when you navigate to it in your own Internet browser. If this occurs, [create a new issue] so that one of the members of the technical team can review the problem and find a workaround. -- As part of its normal operations, GitHub Actions will occasionally go back and re-check old links across this entire site, including old lessons. Therefore, you may see an error being caused not by your lesson, but by another page. If you can see how to immediately fix those errors on other pages, please do so, and then wait for the build to re-run. If you do not have the time to track down those other broken links, first ensure that there are no error links coming from your new lesson, and then [create a new issue] so that someone else on the technical team can review the problem. - -[create a new issue]: https://github.com/programminghistorian/jekyll/issues/new - -## 6) Inform the Editor - -Once the lesson has been published, inform the editor and ensure they have added the lesson to the twitter bot pipeline. diff --git a/en/lesson-framework.md b/en/lesson-framework.md new file mode 100644 index 000000000..e1355bb7a --- /dev/null +++ b/en/lesson-framework.md @@ -0,0 +1,264 @@ +--- +title: Programming Historian Lesson Framework +layout: blank +redirect_from: /author-guidelines +--- + +## _Programming Historian_ Lesson Framework + +{% include toc.html %} + +### Introduction + +#### What is a _Programming Historian_ lesson? + +A _Programming Historian_ lesson is a learn-by-doing resource that empowers readers to develop practical knowledge of a computational method or digital tool, which they will be able to apply in their own research to acquire, transform, analyse, visualise, or preserve data. + +#### Why write a _Programming Historian_ lesson? + +- Deepen your own understanding and knowledge +- Hone your technical writing skills +- Advance your development as a critical, intentional and considered researcher +- Transform research practice into teaching +- Share your experiences of failure to create productive catalysts that help others succeed + +#### Who is the Lesson Framework for? + +This framework is designed to help prospective authors develop lessons that are effective, accessible, and sustainable. It also supports editors and peer reviewers, whose insights and practical feedback are essential to the production of high-quality learning resources. Ultimately, we've created it to empower our readers to learn, adapt, and apply digital methods in their own research contexts. + +#### How to use this Framework + +Prospective _Programming Historian_ authors are encouraged to use this framework as a guide for writing. The needs of each method are different, so the structure and prompts we've included are intended to be flexible. As you write, imagine yourself explaining your method to a colleague or peer. Speak to your reader directly in the second person, using the pronoun 'you'. + +## The Framework + +### Title and abstract + +**Short, descriptive title** +- Begin with verb or a noun to define the main learning activity, method or process. +- Identify the kind of data readers will handle in the lesson. +- Name key tools, software libraries or programming languages readers will use. + +**1-3 sentence, plain-language abstract** +- Summarise the lesson’s core content and its main learning outcomes. + +### Introduction + +#### Method or tool + +**A plain-language overview** +- What is the method/tool? +- What kinds of questions/problems does it support researchers to explore/solve? +- How has it been used in the past? +- How can it be useful in research today? +- Why do you think this method is important? + +#### Technical context + +**Data type/format** +- What kinds of data/data format can this method/tool handle well? + +**Computational resource** +- What level of RAM is needed to complete this lesson? +- Are admin privileges required? +- How large are the sample data files? + - Can the method be scaled for larger datasets? + +**Connectivity** +- After downloading data and installing software, can this lesson be completed offline? + +#### Social context + +**Language** +- Is this method specific to/restricted to specific natural languages? +- In which languages is the graphical user interface/tools’ own documentation available? + +**Ethics** +- Which critical questions of ethics/bias should readers be aware of? + +**Costs** +- Are there any costs involved? +- Is free access tiered or time-limited? +- Do readers need to supply credit card information? + +#### Prerequisites + +**System requirements** +- Which computing environment(s) is the lesson developed for? +- Which programming language release, and software version is used? +- Which operating system(s) has it been tested in? +- Which software packages/libraries need to be installed before starting the lesson? (_if not covered by the lesson_) + +**Knowledge and applied experience** +- What level of familiarity do readers need to have with the method/tool? +- What level of familiarity to readers need to have with the programming language? +- Where can readers gain the knowledge needed to begin? (other _Programming Historian_ lessons, or external resources) + +#### 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 detailed, 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. + +Is your lesson suitable for **beginner**, **intermediate**, or **advanced**-level learners? + +| 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 troubleshooting steps are detailed
• Further _Programming Historian_ lessons (or external resources) for advancing new skills may be referenced | +| **Intermediate** |
• Some prior knowledge is required
• 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
• Existing _Programming Historian_ lessons (or external resources) to empower less experienced readers to gain that knowledge are identified | +| **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 + + +## Use Case + +**Demonstrating application of a method/tool** +- Describe the example ‘use case’ you have selected. +- Why is this use case an appropriate example for demonstrating the application of this method/tool? + +**Example research question/problem** +- What question/problem does this method support researchers to explore/solve in this use case? +- Citation for your case study (if applicable) + +### Dataset + +**Characteristics** +- Describe the sample dataset you’ve provided for readers to experiment with. +- What are the characteristics of this dataset that make it suitable for use with this method/tool? + +**Preprocessing** +- Has the dataset been pre-processed? How? +- Describe any cleaning/labelling (_if not covered by the lesson_). +- If the dataset is selected from a larger corpus, describe the sampling strategy. + +**Citation** + +[IASSIST Special Interest Group on Data Citation – recommended dataset citation components](https://iassistdata.org/file/blog/quick_guide_to_data_citation_high-res_printer-ready.pdf): + +| Component | Description | +|-----------|-------------| +| **Author** | Name(s) of each individual or organizational entity responsible for the creation. | +| **Title** | Complete title, including edition or version number, if applicable. | +| **Date** | Year the dataset was published or disseminated. | +| **Publisher and/or Distributor** | Organizational entity that makes the dataset available by archiving, producing, publishing, and/or distributing the dataset. | +| **Electronic Location or Identifier** | Web address or unique, persistent, global identifier used to locate the dataset (such as a DOI). Append the date retrieved if the title and locator are not specific to the exact instance of the data you used. | + + +### Software/tool + +**Your choice** +- Explain how you selected the software/tool/programming language to achieve the lesson’s goals. +- What are the characteristics that make it suitable for use with this method/tool? + +**Other options** +- Are there multiple options available to achieve the same goals? +- Have you tried these other options? What are their benefits/drawbacks? + +**Citation** + +| [Software Heritage](https://www.softwareheritage.org/save-and-reference-research-software/) recommendations for citing software | +|-----------| +| **Components to include:**
• Author(s)
• Title
• Version
• Year of release
• License
• Repository URL +| **Example citation following the Chicago Manual, 17th edition citation style:**
• **Endnote** Julien Barnier et al.. Scatterd3, version 1.0.1 (2021). GPL. [https://cran.r-project.org/web/packages/scatterD3/index.html](https://cran.r-project.org/web/packages/scatterD3/index.html).
• **Bibliography entry** Julien Barnier, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. [https://cran.r-project.org/web/packages/scatterD3/index.html](https://cran.r-project.org/web/packages/scatterD3/index.html).| + +## Learning keys + +### Concepts + +**What key concepts do readers need to understand before they begin experimenting with this method/tool?** + - Focus on the necessary minimum understandings needed to achieve the objectives of the lesson. + +### Terms + +**Which operational definitions will readers need to understand to work with the vocabulary of the method/tool?** + - Share explanations, rather than definitions. + +**Which specialist words or technical terms will you be using to teach this method/tool?** + - What choices have you made as the author/translator? + - Is the method/tool/programming-specific vocabulary commonly used in a natural language other than the one you’re writing in? + - Are particular terms used differently in this context than in other fields of study? + - Are particular terms contested or under-discussion in the community? + +### Time + +**How long (roughly) do you expect the lesson will take to complete?** + - Are particular steps known to require extended processing/waiting times? + - Are there distinct sections, or natural breaks in the methodology? + +**How does the lesson's structure support effective learning, experiment, and application?** + - Have you organised the lesson into sections? + - What is the main learning activity of each section? + +## Learning experiment + +### Aims + - Reconnect with the [title and abstract](#title-and-abstract) to describe your learning experiment's aims. In the simplest terms, you can think of answering the prompt: _When you have completed this lesson, you will be able to..._. + - What specific, measurable skills and understandings is it designed to develop? + - How will it support your reader to begin using the method/tool to progress towards [working with their own dataset](#local-application)? + +### Inventory +- List the software, packages, and libraries. +- List the sample data files. +- Outline the file directory structure you’ll use in the experiment. + - Why do you recommend this? + +### Workflow + +**Set out the workflow as practical units** +- Include installation of software, packages, libraries. +- Decribe download steps and organisation of data files. + +**Narrate your code** +- Use instructive, reflective narration (rather than inline comments) to guide your reader through the code. +- Break up code blocks to highlight and explain key functions. +- Identify input that is specific to the sample data/would need substitution when applied. +- Clarify where sample code refers to a local directory or URL. + +**Describe processes in general terms** +- No need to detail every action, click or gesture. + - If the [difficulty level](#difficulty) is beyond beginner, you can infer knowledge or applied experience and use specialist or technical terms in context, while taking care to define new terms and explain new concepts as needed. + - If the graphical user interface or tool-specific vocabularly is in a different language than the lesson, you will want to provide additional signposts for navigation. + - Use round brackets to follow a word with its direct translation - either to give a translation from the original language, or the translated language: _Se anota el nodo de origen (source)_, _padrão de nomeação dos branches (ramos)_, or _on a utilisé `px.bar()` pour créer un diagramme en barres (bar chart)_. +- Take care to note challenging or non-intuitive steps. Share suggestions that support your reader to navigate them. + +### Summary + +**Re-cap the learning-experiment** +- What has your reader achieved? + - Refer back to the [aims of your experiment](#aims) to summarise the skills attained, understandings developed, and ideas explored. + +## Local application + +**How can readers apply this method/tool in their own research context?** + +**Use cases and questions** +- Which use cases does the method/tool best support? +- Which research questions/problems might readers start with? + +**Dataset** +- What dataset characteristics are well-suited for use? +- What pre-processing steps might be needed to use a new dataset as demonstrated? (if not covered by the lesson) + +**Working locally** +- If the method uses cloud/web-based tools, what are the options for working locally? + +### Other projects + +Support readers to discover other researchers/projects that have used this method/tool + +Think beyond your domain, your university, your country, and your language community. +- Consider annotating your suggestions: + - What was a particular characteristic of their dataset? + - What interesting challenges did they overcome and how? + +### Continued learning + +Which resources would you recommend to readers who want to continue learning about/experimenting with this method? + +- Share links to open datasets for further practice. +- Suggest _Programming Historian_ lessons or other tutorials. +- Point to research articles developed through use of this method/tool. + +## Endnotes + +We use the endnote system and [The Chicago Manual of Style, 17th Edition](https://www.chicagomanualofstyle.org/tools_citationguide/citation-guide-1.html) for our citations and resources lists. + +- Jennifer Isasi et al., “A Model for Multilingual and Multicultural Digital Scholarship Methods Publishing,” in Multilingual Digital Humanities, edited by Viola, L., & Spence, P., Routledge, 2023. +- Jonathan Reades and Jennie Williams, "Clustering and Visualising Documents using Word Embeddings," _Programming Historian_ 12 (2023), https://doi.org/10.46430/phen0111. diff --git a/en/publishing-workflow.md b/en/publishing-workflow.md new file mode 100644 index 000000000..e5af2fa31 --- /dev/null +++ b/en/publishing-workflow.md @@ -0,0 +1,85 @@ +--- +title: Publishing Workflow +layout: blank +redirect_from: /editor-guidelines +--- + +{% include toc.html %} + +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 | 14 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 | 14 days feedback
45 days submission |
• Managing Editor receives proposal forms.
• Proposal forms are circulated for feedback from the editorial team within 14 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](/lesson-framework#diffiulty).
• 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 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. | | + +### 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. diff --git a/es/guia-editor.md b/es/guia-editor.md index 3a207c2a5..9d66e3c33 100644 --- a/es/guia-editor.md +++ b/es/guia-editor.md @@ -1,7 +1,7 @@ --- title: Guía para editores layout: blank -original: editor-guidelines +original: publishing-workflow --- # Guía para editores diff --git a/es/guia-para-autores.md b/es/guia-para-autores.md index 47bf141c2..72f34bb61 100644 --- a/es/guia-para-autores.md +++ b/es/guia-para-autores.md @@ -1,7 +1,7 @@ --- title: Guía para autores layout: blank -original: author-guidelines +original: lesson-framework skip_validation: true --- diff --git a/fr/consignes-auteurs.md b/fr/consignes-auteurs.md index c49f9e4e7..9e54c8ec1 100644 --- a/fr/consignes-auteurs.md +++ b/fr/consignes-auteurs.md @@ -1,7 +1,7 @@ --- title: Consignes aux auteur(e)s layout: blank -original: author-guidelines +original: lesson-framework skip_validation: true --- diff --git a/fr/consignes-redacteurs.md b/fr/consignes-redacteurs.md index 9e92ec11b..097eea337 100644 --- a/fr/consignes-redacteurs.md +++ b/fr/consignes-redacteurs.md @@ -1,7 +1,7 @@ --- title: Consignes aux rédacteurs et rédactrices layout: blank -original: editor-guidelines +original: publishing-workflow --- # Consignes aux rédacteurs et aux rédactrices diff --git a/pt/directrizes-autor.md b/pt/directrizes-autor.md index 69b226e16..24ba29870 100755 --- a/pt/directrizes-autor.md +++ b/pt/directrizes-autor.md @@ -2,7 +2,7 @@ title: Directrizes para Autores layout: blank skip_validation: true -original: author-guidelines +original: lesson-framework --- # Directrizes para Autores diff --git a/pt/directrizes-editor.md b/pt/directrizes-editor.md index 2f6fcc927..1e0683af0 100755 --- a/pt/directrizes-editor.md +++ b/pt/directrizes-editor.md @@ -1,7 +1,7 @@ --- title: Directrizes para editores layout: blank -original: editor-guidelines +original: publishing-workflow --- # Diretrizes para editores