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, {% include managing-editor.html lang=page.lang %}.

Step 1: Proposing a New Lesson

We welcome tutorials relevant to the humanities, pitched at any level of technical aptitude and experience, that focus on one problem or process, can be sustainable in the long term, and are addressed to a global audience.

The scope and length of the tutorial should be appropriate to the complexity of the task. Tutorials should not exceed 8,000 words (including code). Shorter lessons are welcome. Longer lessons may need to be split into multiple tutorials.

If you have an idea for a new lesson, complete a lesson proposal form and send it to {% include managing-editor.html lang=page.lang %}.

You can get a sense of what we publish by looking through our published lessons, reading our reviewer guidelines or browsing lessons in development. Please also take a moment to check our Lesson Concordance document 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 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

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

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.

Upon acceptance, you agree to publish your lesson under a Creative Commons "CC-BY" license.

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:

Sustainable Writing

Programming Historian publishes lessons for the long-term. Please follow these sustainability guidelines when writing:

Authors should consult our 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

Numbers

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:

Style:

Or:

  1. Here is an item
  2. Here is another item
  3. Here is the final item

Punctuation

Capitalisation

The guideline is to use them sparingly in the running prose. Specific rules:

References

Challenging Words Explained

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. A template for writing your lessons has been provided.

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, TextWrangler, TextEdit, MacDown or Notepad++. For a gentle introduction to Markdown formatting see Getting Started with Markdown, or the concise reference GitHub Guide to 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:

Bold, Italics, and Underline

To ensure consistency across lessons, adhere to the following text formatting guidelines:

Bold

Italics

Underline

Alerts and Warnings

If you want to include an aside or a warning to readers, you can set it apart from the main text:

<div class="alert alert-warning">
 Be sure that you follow directions carefully!
</div>

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 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 %}

{% include figure.html filename="IMAGE-FILENAME" 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:

They will look like this

and this respectively.

-- Follow best practice in writing your code:

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.

  1. Getting Access: create a free Github account. 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 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", 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, 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.

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.