Edit the documentation#

2i2c’s documentation should be dynamic and constantly changing. It is important that our documentation reflect our current practices, so that other team members know how to contribute and what to expect.

These sections cover the major ways that you can make edits to our documentation.

Make edits with the GitHub UI#

The easiest way to edit documentation is to use GitHub’s user-interface directly. This will allow you to make changes in your browser, and propose them via a Pull Request.

To do so here are some basic steps:

Trigger “Edit Mode” in the GitHub UI#

There is a little pencil icon () in the the top-right of the page. Click on it, and it will turn on “editing mode”.

Make your edits#

Make edits to the page’s markdown as you wish. For information about how to write MyST Markdown in our documentation, see Write content with MyST markdown.

Create a Pull Request#

When you’re done making your edits, click Create a new branch for this commit and start a pull request. This will create a Pull Request with your proposed changes.

In the Pull Request, give it a title and description that describe the changes you’ve made. If the edits are very minor, don’t hesitate to merge them yourself (e.g., correcting a typo). If they are more complex, ping a team member for a review.

Edit documentation locally#

If you are comfortable with or interested in learning Sphinx-based documentation workflows, you can also make changes to documentation locally on your computer, push it to GitHub, and then propose a Pull Request.

Learn ahead of time

This section assumes you have a basic knowledge of how to use git. See the Software Carpentry training on git to learn how to use this tool.

Set up a local documentation environment#

To do so, see Set up a local documentation environment.

Clone the repository source files#

First, clone the source files for the repository you wish to edit. For example, to clone the source files of the Team Compass:

git clone https://github.com/2i2c-org/team-compass
cd team-compass

Make your changes#

Edit the markdown files in the Team Compass and the content will be updated. For guidance on how to write MyST Markdown, see Write content with MyST markdown.

Preview your changes (optional)#

To preview your documentation locally, see the instructions on installing and using nox.

This will build the book using Sphinx, and put HTML outputs in an output folder in _build/. You can then preview them by opening up one of the .html files in a web browser.

Push your changes to GitHub and make a Pull Request#

Once you’ve made your local changes, commit them to the repository, push it to GitHub, and open a Pull Request.