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.
You need a GitHub account to create or edit documentation. You can create a Github account here.
Login to GitHub#
Go to 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 github
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.
Suggest an edit#
Click the suggest edit button to begin the process of changing the text.
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!
Make your fixes#
Once you’ve clicked the fork button, you’re ready to make your update in the web editor.
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
Preview your changes#
Click on the “Preview” tab to see what your changes look like. You can click this tab whenever you want to take a look at your work.
The GitHub “Preview” tab will not always show, or render, everything perfectly.
As you can see, both the “Note” box and the part that starts with
display correctly on docs.openedx.org, do not render correctly in the GitHub preview.
Solutions to this problem are to install a local development environment (How-To article TBD), or rely on the “pull request build”, discussed below.
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.
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.)
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.
This will bring up a form which you don’t need to make any changes in for now.
Create pull request button again and you will have a published
Congratulations, you have made a new pull request for a change against the Open edX documentation!
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.
Viewing the pull request build#
As mentioned above, sometimes you can’t use the Preview to see everything rendering properly. Thus, you can use the build on your pull request. At the bottom of your pull request, there is a section that show you the checks on your pull request. If the Docs build is successful, you’ll see it with a green checkmark:
If you click the “Details” link, you’ll be brought to this page:
Click the “View docs” link, NOT the button, to see the build - that is, the set of documentation generated by your changes.
You’ll be brought to a site that looks exactly like docs.openedx.org, but you’ll see the URL looks different and a warning box shows. This is a special site made just for your changes! Navigate to page(s) you’ve changed to double-check your changes look right.
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.
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.