publishing.qmd

---
title: "Publishing OTTR Courses"
format:
  html:
    toc: true
    toc-depth: 4
    toc-location: right 
---

Below are some examples of courses created using the [OTTR Template](https://github.com/ottrproject/OTTR_Template) and published on three platforms: Bookdown, Leanpub, and Coursera.

*Introduction to Reproducibility in Cancer Informatics:*

- [GitHub repository and source code](https://github.com/jhudsl/Reproducibility_in_Cancer_Informatics)
  - [Bookdown website](https://jhudatascience.org/Reproducibility_in_Cancer_Informatics/introduction.html)
  - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-for-research-leaders)
  - [Coursera course](https://www.coursera.org/learn/intro-reproducibility-cancer-informatics)

*Computing for Cancer Informatics:*

- [GitHub repository and source code](https://github.com/jhudsl/Computing_for_Cancer_Informatics)
  - [Bookdown website](https://jhudatascience.org/Computing_for_Cancer_Informatics/)
  - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-computing)
  - [Coursera course](https://www.coursera.org/learn/computing-for-cancer-informatics)


# Publishing with Bookdown

To publish your content using Bookdown, utilize GitHub Pages by following the [repository setup instructions](getting_started.html). Note that Bookdown is a prerequisite for Coursera and Leanpub publishing. You must publish with Bookdown before using those platforms.

As you add or rename chapters, update `_bookdown.yml` accordingly. For example, after adding `03-new_chapter_of_course.Rmd`:

```{yaml}
book_filename: "Course_Name"
chapter_name: "Chapter "
repo: https://github.com/ottrproject/OTTR_Template/ ##Make sure you update this to your GitHub Repo!!
rmd_files: ["index.Rmd",
            "01-intro.Rmd",
            "02-chapter_of_course.Rmd",
            "03-new_chapter_of_course.Rmd",  ## This is the only new line!
            "about.Rmd"]
new_session: yes
delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "
output_dir: "docs"
```

Only a single line changes. Be careful with quotation marks (`""`) and commas (`,`).

Preview the book by running `bookdown::serve_book()` in the RStudio Console. This generates an `.rds` file you can ignore. The live preview will appear in your RStudio Viewer.

When a pull request is merged to main, [GitHub Actions](#github-actions) will re-run `bookdown::render_book()` and add the results to `main`.

# Publishing with Leanpub

OTTR includes everything needed to publish to [Leanpub](https://leanpub.com/). The [`ottrpal` package](https://github.com/ottrproject/ottrpal) handles converting content into a Leanpub-ready format, storing output in the `manuscript` folder.

::: {.callout-warning}
Do not manually edit files in the `manuscript` folder. It is auto-generated by `ottrpal` and will be overwritten.
:::

If you want quizzes and answers hidden, you will need a separate private OTTR_Quizzes repository. [Start with these instructions](publishing.html#quizzes-repository-checklist) before proceeding.

## Leanpub Rendering

The `ottrpal` package handles most formatting for links and other elements, as long as you have followed the [image formatting instructions](writing_content_courses.html#set-up-images).

GitHub Actions will attempt to convert Bookdown to Leanpub by running `ottrpal::bookdown_to_leanpub()` at the top of the repository.

### Setting up Leanpub-related GitHub Actions

When ready to publish to Leanpub, enable the following in your [`config_automation.yml`](customize-robots.html):

- `render-leanpub: yes`
- `check-quizzes: yes`

You may also configure chapter and quiz ordering. By default, `make-book-txt: TRUE` orders content by filename numbering. Set `make-book-txt: FALSE` if you want to specify ordering manually via a `Book.txt` file. Read more in the [quizzes section](#setting-up-quizzes).

After updating `config_automation.yml`, file and merge a pull request. Quiz formatting will be checked automatically and reported in a pull request comment.

File issues with the `ottrpal` package in its [GitHub repository](https://github.com/ottrproject/ottrpal/issues).

## Hosting your course on Leanpub

Finalizing a course on Leanpub can be tricky. The [Using Leanpub](https://hutchdatascience.org/Using_Leanpub/index.html) guide provides detailed help.

1. Create a [Leanpub account](https://leanpub.com/) if you do not have one.

2. Start a course:
   - Click the three-line button at the far right of the top bar.
   - Click the **Author** tab, then **Courses**.
   - Verify your email address if prompted.
   - Click `create a new course`, then **A Course**.
   - Provide a title (the Course URL fills automatically).
   - Select **Using Git and GitHub**.
     - JHU developers: follow [this additional setup document](https://docs.google.com/document/d/18UQicXwf8d25ayKGF2BrinvRgB_R2ToVn5EDOUcxyoc/edit?usp=sharing).
   - Press `add to plan`.

3. Preview a new version:
   - Click the three-line menu, then the **Author** tab, then **Courses**.
   - Click your course name or icon.
   - Click **Preview New Version**, then `Create Preview`.

If the render fails, it is typically due to a quiz formatting error. Occasional failures may also occur due to sync lag between GitHub and Leanpub — try again if it fails once.

## Setting up quizzes {#setting-up-quizzes}

Store quizzes in the `quizzes/` directory. Use the [template quiz](https://github.com/ottrproject/OTTR_Quizzes/blob/main/quizzes/quiz_ch1.md) as a starting point. All quizzes must be written in [Markua format](https://leanpub.com/markua/read#leanpub-auto-quizzes-and-exercises).

After adding each quiz, add its filename to the `Book.txt` file at the top of the repository (not the one in `manuscript`) in the correct position. For example, with two quizzes interleaved between three chapters:

```
01-intro.md
02-chapter_of_course.md
quiz_1.md
03-chapter_of_course.md
quiz_2.md
about.md
```

Files listed with a `#` prefix in `Book.txt` are ignored by Leanpub.

You cannot have two quizzes with the same `quiz_id`. See an [example quiz here](https://github.com/ottrproject/OTTR_Quizzes/blob/main/quizzes/quiz_ch1.md).

### Leanpub quiz question types

**Standard multiple choice** — answer choices are not randomized:

```
? A question is here
a) A wrong answer
B) A correct answer has a capital letter
c) A wrong answer
d) A wrong answer
```

**Choose answers** — randomizes choices using `C)` for correct, `m)` for mandatory incorrect, and `o)` for optional incorrect. The number of answers must be at least equal to the count of correct and mandatory incorrect answers.

```
{choose-answers: 4}
? A question is here
C) The correct answer is signified with a capital C
m) A mandatory incorrect answer
m) A mandatory incorrect answer
o) An optional incorrect answer
o) An optional incorrect answer
```

Upon merging to `main`, the `check-quizzes.yml` GitHub Action validates quiz formatting and reports errors on the pull request.

### Leanpub quiz format rules

- Quizzes start and end with `{quiz}` and `{\quiz}` tags.
- No exclamation points or colons in answers.
- At least one correct answer per question.
- All question and quiz attributes must be recognized by Leanpub.
- All quizzes must be listed in `Book.txt`.
- The `choose-answers` count must be at least as large as the number of mandatory and correct answers.

## Converting quizzes from Leanpub to Coursera format

Convert quizzes to a Coursera-uploadable YAML file by running:

```{r, eval=FALSE}
ottrpal::convert_quizzes()
```

Note that images and links are not currently supported by the conversion script and must be added manually. Colons (`:`) are not allowed in prompts or answers.

[See full Coursera publishing instructions](course_publishing.html#publishing-with-coursera).

## `_Quizzes` repository checklist

- [ ] A [`GH_PAT` has been set](https://www.ottrproject.org/getting_started.html#6_Set_up_your_GitHub_personal_access_token) in both the main Template and the `_Quizzes` repository.
- [ ] [Leanpub course has been created](#hosting-your-course-on-leanpub).
  - [ ] Writing mode is set to `GitHub` and linked to your main OTTR_Template repository.
- [ ] `_Quizzes` repository is set to `private`.
  - [ ] `main` branch protection is configured:
    - [ ] `Require pull request reviews before merging` is checked.
    - [ ] `Require status checks to pass before merging` is checked.
    - [ ] `Require branches to be up to date before merging` is checked.
- [ ] Repository is [enrolled in automatic updates](enroll_sync.html).
- [ ] `Book.txt` is up to date.
- [ ] [`ottrpal::bookdown_to_leanpub()` ran successfully](#leanpub-rendering).


# Publishing with Coursera

Once your content is extensively developed, consider publishing on Coursera.

::: {.callout-note}
This guide was prepared for [ITN project](https://www.itcrtraining.org/) developers at Johns Hopkins University or other Coursera partner institutions. Coursera's Educator Resource Center is the authoritative source for platform documentation.
:::

## Setting up your Coursera course

**If you are from Johns Hopkins:** Follow [this document](https://docs.google.com/document/d/1aZeOSFLkK4hZne4Vb1iaP_0H4zyhIwvbnw9sbdCFq1Y/edit?usp=sharing) and contact Ira Gooding (iragooding@jhu.edu) to create a course shell.

**If you are not from Johns Hopkins:** Set up your educator profile and course shell through your own institution.

## Converting your files for Coursera

GitHub Actions (in `render-all.yml`) renders your course in a Coursera-compatible format — identical to the standard version but without the left-side table of contents. These files are available in the `docs/no_toc` folder. A preview link is posted as a GitHub comment by `render-preview.yml`.

If quizzes were written in Leanpub format, `pull-request.yml` converts them automatically for Coursera upload. Alternatively, you can write quizzes directly on Coursera's website and download them as YAML for storage in your repository.

## Navigating to your course on Coursera

Go to **My Courses** in your Coursera profile. Your course will appear in the list. Click **Go to Course**, then **Edit Course** in the upper right corner.

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/profile.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/my-courses.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/edit-course-nav.png)

Select your version (initially Version 1):

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/versions.png)

You are now on the Edit content page:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/edit-content.png)

Each lesson should contain at least one chapter and one quiz. Each module represents approximately one week of learner work — plan one or two lessons per module accordingly.

Click `+ Add Lesson` to add a new lesson:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-lesson.png)

### Adding chapters to Coursera

Chapter URLs follow this pattern, using your GitHub Pages URL with `/no_toc/` inserted before the filename:

```
<main-github-pages-url>/no_toc/<html_filename>
```

Find your GitHub Pages URL under `Settings` > `Pages`. For example:

```
https://ottrproject.org/OTTR_Template/no_toc/introduction.html
```

To add a chapter: in a lesson, click `+ More` and choose **Ungraded Plugin**.

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-1.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-2.png)

Click the edit button on the new Ungraded Plugin:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-3.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-4.png)

Scroll down and click **Edit Configuration**:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-5.png)

Replace the example URL with your chapter URL:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-6.png)

Click **Save Configuration**:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/new-add-chapter-7.png)

Adjust the time estimate for your content. If the URL is correct, a preview of your chapter appears:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-8.png)

Edit the title if needed, then click **Publish** to save. Coursera will ask you to confirm — click **Publish** again.

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-9.png)

### Adding quizzes to Coursera

From the **Edit content** page, click `+ Quiz` on the lesson where you want to add it:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-1.png)

Click **Edit** on the new quiz:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-2.png)

To import a converted Leanpub quiz, click **Import Questions** and choose your converted YAML file. (If not yet converted, [see the conversion section](#converting-quizzes-from-leanpub-to-coursera-format).)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-3.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-4.png)

Click **Upload**:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-5.png)

If the upload fails, [file an issue](https://github.com/ottrproject/OTTR_Quizzes/issues) with the file and a description of the failure. Note that images, links, and colons in prompts or answers are not supported.

After a successful upload, click **Continue**. Change the quiz type from `Practice Quiz` to `Graded Quiz` as needed using the dropdown on the left. Update the time estimate as well.

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/quiz-settings.png)

Assign learning objectives by clicking the plus sign under the title, selecting applicable objectives, and clicking **Save**:

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/learning-obj-assigned.png)

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/assign-learning-obj.png)

Edit the title if needed, then click **Publish** to save.

## Programmed messages

From **Edit Course**, navigate to `Content` > `Programmed Messages` in the left sidebar. At minimum, add a **Welcome** and a **Completion** message. Click **Preview** then **Publish** to save each.

**Welcome message template:**

```
Welcome to {Course Name}

We hope this course will {What will they learn?}

To get the most out of the course {What do you advise?}

If you ever encounter any problems with the course, have questions or ideas, please let us know using this feedback form.
```

**Completion message template:**

```
Congratulations and thank you for completing {name of course}!

We hope this course has {What do you hope they learned}.

If you have feedback about our course we would greatly appreciate you filling out this form.
```

Add a link to your feedback form using the link icon in both messages.

## Grading formula

From **Edit Course**, navigate to your version page. Set the percentage each module's assignments contribute to the final grade.

![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/grading-formula.png)

## Content schedule

Found under the `Content` tab. Assign modules to weeks of your course here.

## Module descriptions

Located just before learning objectives when editing content. Descriptions help learners know what to expect from each module.

## Landing page

Add a course image and consider including:

- Estimated workload
- Skills covered
- Recommended background
- What students will learn

## Multiple reading formats

Because Coursera uses plug-ins and there are accessibility concerns, add a reading at the very start of your course directing students to alternative formats. Create a reading using the **Add Reading** button (next to **Add Quiz**) and move it to the top of the first module by dragging the three-line icon on the left.

Title the reading:

```
Multiple Lesson Formats
```

Paste and modify the following:

```
Like many of our other courses, the content of this course is available in multiple formats.
You can also find the lessons for this course at [insert Bookdown link here]. This format might be most appropriate for you if you rely on screen-reader technology.
Our courses are open source, so you can also find all the source material on GitHub by visiting [insert GitHub link here].
These resources are used throughout this Coursera course in the form of ungraded plug-ins. You are welcome to use those plug-ins here on Coursera or connect to the content in other formats through the links above. Please select the format that most suits your needs.
Note about links in the plug-ins: The plug-ins used throughout the course feature links to other resources. To follow these links, right-click on them and open in a new tab or window.
Regardless of the format you choose for the instructional content, you must take and pass the quizzes here on Coursera if you want to earn a Coursera certificate.
```