Quick Start: Add New Documentation Through GitHub#

Prerequisites

You need a GitHub account to create or edit documentation. You can create a Github account here.

To contribute to Open edX documentation, you must have a signed contributor agreement. For more information, see How to start contributing to the Open edX code base.

Find Where to Add a New Topic#

The latest documentation is in the main branch of the Open edX Documentation GitHub repository.

Review the Documentation Audiences and Documentation Content Types sections to determine where your addition should be located.

  1. Navigate to the folder where you want to create the new topic.

  2. Ensure the main branch is selected.

Create the New Topic#

In the location where you should create the new topic:, with the main branch selected:

  1. In the Add New File drop-down, select Create New File.

    You receive the following message:

    ../../_images/documentors_fork_message.png

    Followed by the interface for creating a new topic:

    ../../_images/github_create_topic.png
  2. At the top of the screen, give the file a name and the .rst extension.

  3. Add content to the topic as needed.

    Ensure you keep to RST standards in file. See the Documentation Checklist for guidelines, and copy RST code as needed from Documentation Templates.

  4. In the Propose New File section at the bottom of the edit window:

    1. Add a comment about the addition you made.

    2. Optionally, add a longer description.

    3. Click Propose new file to save these changes to your fork.

GitHub then creates a fork of the repository that belongs to your account. A fork is a complete copy of the repository, plus your changes. For more information, see Github Forks.

GitHub then prompts you to create a pull request, which is a request for the Open edX team to integrate changes in your fork into the official repository.

Create a Pull Request for the New Topic#

  1. In the Pull Request window, click Create pull request.

    ../../_images/create_pr_screen1.png
  2. You should not need to change the branches selected. By default, you are requesting to merge the branch in your fork of the repository into the official repository’s main branch.

  3. Add a unique, descriptive title for your pull request.

  4. Add a comment that explains your change to the Open edX team.

  5. Ensure the checkbox “Allow edits by maintainers” - this enables the Open edX team to rerun tests or make small changes, which will decrease the time for your changes to be accepted. Your screen should look like this:

    ../../_images/create_pr_screen2.png
  6. Click Create pull request.

The Open edX team will then review your changes. If they approve, they will merge the pull request, and you will see your changes in the latest documentation. The Open edX team may ask you to make further changes, to clarify the documentation or fix issues.