Copyediting

Publishing Tasks: Phase 6 Sustainability Accessibility

Copyediting (original lessons only)

---

Contents of this page:

• General Notes about Copyediting
• Copyediting Workflow
• Important Considerations

---

General Notes about Copyediting

• Copyediting is more involved than proofreading, because it often requires changing the wording, the sentence structure, and sometimes even the whole lesson structure.
• Our lessons are written in a different register than traditional academic articles: they tend to sound more conversational, or personable. We try not to overuse complex language, and mostly try to write in the second person (addressing the reader as 'you').
• We call our articles 'lessons', not 'tutorials': this word has to be changed throughout if needed.
• Our lessons should respect the word limit (8000 words, including code), but we remain flexible about this.
• A key part of copyediting is to read the lesson from the point of view of a beginner. You may ask yourself: "Do I understand everything I need to do, based only on the information the lesson gives me?"; "Does it feel clear, coherent?"; "Is anything missing which would improve the explanation?".

Copyediting Workflow

Copyediting happens in Phase 6 (Sustainability and Accessibility). At this stage, the author has already completed two rounds of revision: one after the editor's initial feedback, and another after the two peer reviewers' feedback. Everyone is happy with the content of the lesson, and we are now working on how to deliver this content in the most effective way.

The copyediting stage must happen when and only when these two comments have been posted in the issue (usually by the Publishing Manager):

• The mermaid diagram describing the phase change from 5 (Revision 2) to 6 (Sustainability & Accessibility)
• The pre-copyediting announcement comment asking authors not to touch the original file anymore

These are the steps to copyedit a lesson in GitHub:

1. Open a branch from gh-pages in the ph-submissions repository called copyedit-lesson-slug. The lesson slug can be found in the links to the lesson files, which are usually in one of the first comments posted in the related issue.
2. Open the lesson preview (http://programminghistorian.github.io/ph-submissions/en/drafts/originals/lesson-slug) and read it once fully, making note of things that come to mind (general mistakes, feeling of structure, obvious issues, etc.).
3. Within the copyedit branch, navigate to the lesson-slug.md file containing the lesson text.
4. Then, work through the lesson, as many times as needed. This may require combing through it fully 2 or even 3 times, because it is easier to get a better sense of the lesson as a whole by the second read. This is especially true for understanding how well the structure flows, or how concepts are introduced, then built upon later. Reading to the end of the lesson multiple times may help the copyeditor to better clarify some of the more obscure passages, as they will have gained a deeper understanding of what the author is truly aiming to express.
5. Make notes as you work through the lesson, to remember what issues need to be flagged or addressed. Notes are helpful when making big changes (structure, strong editorial choices), or when there are questions that cannot be resolved without the author's input.
6. Once all the changes are committed, create a Pull Request and prepare the following steps:

• The description should read something like this:

I've now prepared my copyedits for [EN_ES_FR_PT/lesson-slug], represented in Issue #XXX.

• If you made any substantial changes you want to point to specifically, or if you need the author's input about anything: Under Files Changed, click on the small blue + sign in front of the relevant line (on the green side). Use the comment space to explain what change you made and why (or ask a question), then click Add single comment (NOT Start a review).
• In the PR's Conversation tab, post the Pull Request comment and adjust the placeholders as needed. This will involve taking a screenshot of the Edit File button under Files Changed (new screenshot for every lesson).
• Request the author's review for the Pull Request by clicking (or searching for) their GitHub username under Reviewers.
• In the lesson's issue, post the Issue comment to let all the contributors know that the copyedits are ready for their review.
• The author and editor may simply accept all the changes immediately, or they may engage in some back and forth to solve certain issues, before the Pull Request is ready to be merged.

Important Considerations

• Check the spelling, punctuation and grammar in all of the lesson text. This includes:

  • the lesson body
  • the alt text and captions in the figures' liquid syntax
  • the abstract and avatar alt text in the YAML header, at the very top
  • the endnotes and/or bibliography, when present
  • the in-line comments in the code blocks (starting with a hashtag)

• Focus on making sure that the lesson is well-written and pleasant to read. It's important to keep the language clear, lucid and correct. For this, it is best to prioritise short sentences and straightforward instructions. It can be helpful to break down long sentences, and remove unessential words, sentences or even whole paragraphs! Sometimes, paragraphs work better as bullet points, or numbered lists. Copyediting may even involve adding a sentence or two for further clarification, especially when steps are too vague. If there are difficult technical terms that are not explained, you can embed links to a relevant Wikipedia page (if it exists).

• Ensure that the signposting is accurate and sufficient throughout the lesson:

  • Consecutive steps are numbered or introduced in a clear, coherent way.
  • Where the author refers to another section in the lesson, ensure they are linking to it using [Section Name](#section-name); check the section actually exists; and check that the information they are referring to is actually found within. (Sometimes, headings may have been renamed or removed.).
  • We cannot link directly to figures in the lesson, but you should make sure that any mention of a figure includes its number. For example: "as seen in Figure 4 above [...]". Take this opportunity to also ensure that the image does clearly show what is being discussed.
  • Also check that filenames, website names, tabs, etc are consistent throughout, as sometimes small mistakes slip through. This involves carefully reading through the lesson as though you were actually following it as a reader, and making notes of important pieces of information that should not contain any mistakes.
  • Check that acronyms are introduced in full the first time they are used, then used consistently. An acronym could be reintroduced later down if the lesson uses many acronyms, or if we haven’t encountered it for a long time.

• Remember that our lessons are written for a global audience: readers will come from very different cultural backgrounds. 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). Use generic terms rather than trademarks (tissue rather than Kleenex). Links to Wikipedia should be used liberally to give context where needed. Be aware that historical events often have different names in different countries. Similarly, 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.

• Think about the overall structure of the lesson: do the paragraphs/sections make sense in this order? Would it be better if certain things came before/after others? Are the headings structured in a sequence that makes sense? It may be helpful to pull out all the headings into a separate list and determine whether they work well in that order, especially when there are many subheading.

• If there is a very important piece of information (warning, alert, notice), this can be set apart from the main text using the div box syntax (note that you must use html and not markdown inside the boxes):

<div class="alert alert-info">
Blue information boxes can be created using HTML. We use <a href='https://getbootstrap.com/docs/4.0/components/alerts/'>Bootstrap Alerts</a> formatting.
</div>

<div class="alert alert-warning">
Yellow warning boxes can be created using HTML. We use <a href='https://getbootstrap.com/docs/4.0/components/alerts/'>Bootstrap Alerts</a> formatting. 
</div>

What you don’t need to consider during copyediting:

• The code: it should have already been checked and double-checked in the previous revisions. The only exception is when the copyedits reveal that we need to change a file name, a link, or another important piece of information that is used inside the code: in that case, you should update and adjust the code as needed.
• Typesetting: the use of bold, italics, backticks, etc. The Publishing Assistant carries out these checks after the copyedits are merged.