Contributing

Ready15 is living, breating document maintained through community efforts.

If you would like to contribute but don’t know how, you’ve come to the right place! Before adding to the documentation, remember that all members of our community are expected to follow our Code of Conduct. Please make sure you are welcoming and friendly in all of our spaces.

Ready15 uses reStructuredText and Sphinx to generate HTML which is then hosted on GitHub Pages using the Read the Docs theme.

Getting started

First steps

At a minimum, the only things you will need to contribute are a web browser, an Internet connection, and a GitHub account (you can register for a free account if you don’t have one).

If you’re making small changes to the documentation, using the Github UI is the simplest method. Otherwise, we suggest setting up a development environment on your computer to better verify changes locally before pushing upstream.

Contributing through the GitHub UI

If you find an error on a page, or would like to make a minor amendment you can verify those changes through the documentation generated when you open a pull request and can be accessed using the Github UI.

  1. on a Ready15 page, click the Edit on GitHub link in the top right corner

  2. on the tab that opens, click the pencil icon to the top right of the document. This will Fork this project and edit the file

  3. make your changes and click the Propose changes button

  4. review your changes and click Create pull request when ready

  5. on the pull request page, fill in details about the changes you’ve made to allow us to better review, and click Create pull request when ready

  6. your pull request has been created and one of the Ready15 maintainers will review your changes. When accepted, a maintainer will merge, and the website will be automatically updated!

Contributing from your local machine

If you’re making large changes to the documentation, you may want to verify those changes locally before pushing upstream.

  1. clone the ready15.com repository:

    $ git clone --recurse-submodules https://github.com/RhysDeimel/ready15.git

  2. create a virtual environment with Python 3.9, activate it, and upgrade pip:

    $ cd ready15.com
$ python3.9 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

  3. install documentation requirements

    (.venv) $ pip install -r docs/requirements.txt

  4. build and display the documents

    (.venv) $ cd docs
(.venv) $ make livehtml

  5. the documents will be available at http://127.0.0.1:8000/ and will rebuild each time you edit and save a file.

Guidelines

Please follow these guidelines when updating our docs. Let us know if you have any questions or something isn’t clear.

The optimal section length is 7 minutes. This equates to 1400~1750 words. If a page exceeds this, consider breaking it into multiple pages.

For page titles, or Heading1 as they are sometimes called, we use title-case.

If the page includes multiple sub-headings (H2, H3), we usually use sentence-case unless the titles include terminology that is supposed to be capitalized.

  • Do not break the content across multiple lines at 80 characters, but rather break them on semantic meaning (e.g. periods or commas). Read more about this here.

  • If you are cross-referencing to a different page within our website, use the doc role and not a hyperlink.

  • If you are cross-referencing to a section within our website, use the ref role with the label from the autosectionlabel extension.

Where to go from here

This is the end of the contribution page.

Here you have some resources to continue learning about documentation and Ready15:

  • To make the most of the documentation generator you can read the Sphinx tutorial.

Happy documenting!