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 moving parts of the text around.
• 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 we the prioritise the use of clear, concise language, and short sentences.
• Most lessons are best written 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).
• 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 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.).
2. In the ph-submissions repository, navigate to the copyedit-lesson-slug branch (or create it from gh-pages if needed), then open the lesson-slug.md file containing the lesson text. You can find the link to this file in one of the first comments posted in the lesson's related issue, or you can navigate through the directories (en/es/fr/pt > drafts > originals/translations > lesson-slug.md).
3. 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.
4. 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.
5. 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.

6. Finally, merge the Pull Request and delete the copyedit branch.

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 (found in the YAML header, which is always at the very top of the page and indicated by two sets of --- signs)
  • the endnotes and/or bibliography, when present
  • the in-line comments included the code blocks (lines 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, consistent 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 pieces of information that are crucial to successfully completing the lesson.
  • 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.
  • Be attentive to extended or multi-part numbered lists, which can become confusing for readers to navigate.

• 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 subheadings.

• 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 filename, 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.