Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shorten Editorial Guidelines #992

Closed
acrymble opened this issue Aug 21, 2018 · 1 comment · Fixed by #999
Closed

Shorten Editorial Guidelines #992

acrymble opened this issue Aug 21, 2018 · 1 comment · Fixed by #999
Assignees

Comments

@acrymble
Copy link

acrymble commented Aug 21, 2018

Pending the outcome of the following tickets:

#991 - New Lesson Template
#972 - Update Metadata example in Auhor Guidelines

We could reduce the number of steps in the Editorial Gudelines, which are becoming dauntingly long, and a number of editors have found it difficult or have missed steps when trying to publish lessons. In particular, the "Acceptance and Publication" checklist, which currently has 12 items:

    1) Move the Files
    2) Create an Author Bio
    3) Add a table of contents to the lesson
    4) Add reviewers and editors to the YAML file
    5) Add a difficulty indicator to the YAML file
    6) Add the review ticket URL to the YAML file
    7) Update the date field in the YAML file
    8) Other lesson YAML finalization
    9) Find an Image to represent the lesson
    10) Incorporate your lesson into our Twitter bot
    11) Confirm all links and YAML headers are functioning correctly
    12) Thank Everyone and Encourage Promotion

Propose Following Changes to those sections:

Section Solution
1) Move the Files Move to "Managing Editor" checklist - see #983 - Managing Editor transition. This would become the "Managing Editor's" responsibility
2) Create an Author Bio no change
3) Add a table of contents to the lesson Add table of contents to the lesson - see #991 - added to new lesson template and included by authors from the start.
4) Add reviewers and editors to the YAML file condense with 4, 5, 6, 7, 8, into "verify YAML data" step to make it look less daunting
5) Add a difficulty indicator to the YAML file condense with 4, 5, 6, 7, 8, into "verify YAML data" step to make it look less daunting
6) Add the review ticket URL to the YAML file condense with 4, 5, 6, 7, 8, into "verify YAML data" step to make it look less daunting
7) Update the date field in the YAML file condense with 4, 5, 6, 7, 8, into "verify YAML data" step to make it look less daunting
8) Other lesson YAML finalization condense with 4, 5, 6, 7, 8, into "verify YAML data" step to make it look less daunting
9) Find an Image to represent the lesson no change
10) Incorporate your lesson into our Twitter bot no change
11) Confirm all links and YAML headers are functioning correctly Move to "Managing Editor" checklist - see #983 - Managing Editor transition. This would become the "Managing Editor's" responsibility
12) Thank Everyone and Encourage Promotion no change.

So the new section would be:

    1) Create an Author Bio
    2) Verify YAML data
    3) Find an Image to represent the lesson
    4) Incorporate your lesson into our Twitter bot
    5) Ask the Managing Editor to verify and publish the lesson
    6) Thank Everyone and Encourage Promotion

and the Managing Editor Section would be:

   1) Look over the preview for any obvious errors.
   2) Move the Files
   3) Confirm all links and YAML headers are functioning correctly
   4) Inform lesson editor that the lesson is published.
@arojascastro
Copy link
Contributor

I like it, it would make everything simpler for most of editors, but this means that the managing editor has to invest more time and effort. I guess the upcoming managing editors should be aware of this. Otherwise, lessons will be stuck in the pipeline.

@acrymble acrymble self-assigned this Aug 27, 2018
acrymble pushed a commit that referenced this issue Aug 30, 2018
New text for translating:

## Acceptance and Publication - Editorial Checklist

Once you and the author are happy with a tutorial, the next step is to begin the publication process.

...

### 3) Add YAML metadata to the lesson file

title: ["YOUR TITLE HERE"]
collection: lessons
layout: lesson
slug: [e.g. sentiment analysis]
date: [YYYY-MM-DD]
translation_date: [YYYY-MM-DD (translations only)]
authors:
- [FORENAME SURNAME 1]
- [FORENAME SURNAME 2, etc]
reviewers:
- [FORENAME SURNAME 1]
- [FORENAME SURNAME 2, etc]
editors:
- [FORENAME SURNAME]
translator:
- [FORENAME SURNAME (translations only)]
translation-editor:
- [FORNAME SURNAME (translations only)]
translation-reviewer:
- [FORNAME SURNAME (translations only)]
original: [slug to original published lesson (translations only)]
review-ticket: [e.g. programminghistorian/ph-submissions#108]
difficulty: [see guidance below]
activity: [ONE OF: acquiring, transforming, analyzing, presenting, sustaining]
topics: [see guidance below]
abstract: [see guidance below]

- **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 to the lesson, include the following in the YAML file:
- **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.

...
### 6) Inform the Managing Editor to Publish

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

# Managing Editor Checklist

The Managing Editor is responsible for moving the files to the main website via a pull request. This is also a chance for the managing editor to familiarize him/herself with the new lesson, and to quickly check that everything looks ok.

## 1) Look over the submission preview

Check the submission preview for any obvious errors such as broken images or strange formatting. Inform the editor of any mistakes, which they are responsible for getting fixed.

...

## 4) Inform the Editor

Once the lesson has been published, inform the editor.
acrymble pushed a commit that referenced this issue Sep 5, 2018
Requires a close read by a Spanish speaker.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants