Quick Start: First Documentation PR#

This quickstart will walk you through the process of making an update to a piece of documentation on docs.openedx.org.

Prerequisites

Important

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

Login to GitHub#

Go to https://github.com/login

If you are not already logged in, go ahead and login. If you are already logged in, GitHub will redirect you to the homepage https://github.com

Find a Page to Update#

First let’s find a page in the documentation that needs to be updated.

Go to the Sample Document with Errors

This page has a spelling error that we want to fix, let’s go to the source and make a change.

A screenshot of the bad spelling of the word spelling on the sample page.

Suggest an edit#

Click the suggest edit button to begin the process of changing the text.

A screenshot of the sample page with the 'suggest edit' link highlighted.

Fork the repository(repo)#

If you have never made a pull request to this repo, you’ll be asked to fork the repo. A “fork” is essentially your own copy of the repository.

Go ahead and click the big green button!

A screenshot of the github page for forking a repository. With the "Fork this Repository" button highlighted.

Make your fixes#

Once you’ve clicked the fork button, you’re ready to make your update in the web editor.

A screenshot of the github editor with the contents of the doc_with_errors.rst file.

Go to line 11 and fix the spelling error.

While we’re here let’s also highlight some text we want to emphasize on this page. You can bold text by adding ** before and after the text you want to bold. Go ahead and do that now around the sentence Small changes add up!

It should end up looking something like:

I really want to emphasize the following: **Small changes add up!**

The format that the documentation is using is called reStructuredText or RST for short. If you want to learn more about what RST can do, check out the RST Quick Reference Quick Reference: Writing RST

Save your changes#

Now that you’ve made the change, scroll down and add some notes about the change and get it ready for review by a project maintainer.

To help the maintainers review the change, let’s add a small description that gives them context about what we changed and why.

A screenshot of the "Propose Changes" form with the suggested text. The subject is the same but the description has two bullet items to indicate that we've fixed the spelling and have emphasized some text.

Once you’ve added a description, go ahead and hit the Propose Changes button. This will save your changes to your fork and allow you to make a pull request that (more on that shortly.)

A screenshot of the "Propose Changes" form with the "Propose changes" button highlighted.

Making a pull request#

The next page will give you a chance to review your changes before you ask others to do the same.

By making a pull request you will notify the maintainers about the change and officially request that they review the changes and accept them.

Go ahead and hit the Create Pull Request button.

A screenshot of the github page comparing changes with the "Create pull request" button highlighted.

This will bring up a form which you don’t need to make any changes in for now.

A screenshot of the github PR form with the "Create pull request" button highlighted.

Click the Create pull request button again and you will have a published Pull request!

A screenshot of a submitted github PR.

Congratulations, you have made a new pull request for a change against the Open edX documentation!

Animated confetti.

Because this was a practice PR, it will be closed without the changes being accepted. This is so others can continue to go through the same quickstart.

However for any real changes you make in the future, you can expect that the reviewers will review your changes and may ask for changes or accept your changes as is and merge them.

Note

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

If you need more help or run into issues, check out the Getting Help section of the documentation for links to some places where you could get help.