Quick Start: First Documentation PR
Contents
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.
Steps to Making your First Documentation PR
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.
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
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.
Click the Create pull request
button again and you will have a published
Pull request!
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.
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.