This page describes a lightweight way for anyone to make changes to pages they find in the edX or Open edX documentation. The original source for our docs are stored as ReStructured Text (.rst) files on GitHub. Changes are suggested using GitHub pull requests.

Prerequisites

You will need a GitHub account, and you will need to be onboarded as an Open edX contributor.

Editing a page

1. Find the page you want to change
   Navigate to the published page you want to change, for example starting from https://docs.openedx.org or https://docs.edx.org.

2. In the upper-right is a GitHub icon. Click it to get a drop-down menu, and select “Suggest edit” from it:

   

3. This will take you to a page on GitHub with an editor for the .rst file:
   

   

4. Edit the page in that editor to make your changes. This might involve details of .rst sytnax, cross-references, and so on. [Link to resources….]

5. When you are ready, click the green “Commit changes…” button in the upper right. It will present you with a form to fill out:
   

   

6. The commit message should be like an email subject line. What did you change? Commit messages start with a prefix indicating the type of change. For content changes, use “docs:” as the prefix.

7. Click “Propose changes”. This take you to a page to create a pull request. This is GitHub’s term for a proposed change:
   

   

   You can add more detail to the description of the changes, including links to supporting materials, and so on.

8. You will need someone to review your change. Use the Reviewers section in the right sidebar to select a reviewer.

9. Click “Create pull request”. Now the bottom of the pull request page will have a number of checks:
   

   

   The readthedocs.org checks are the most useful. When they are done running, the Details links on the right will take you to readthedocs to see how your changes will actually publish.