Link

Contributing to the Guides

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The goal of the open-source AFWERX Guides project is for members of the community to contribute and improve the guides.

The project is beginner-friendly and we hope many people are able to make their first open-source contribution through this project.

You can help improve the guides in three ways:

You need a Github account to contribute, but you can do everything entirely through your web browser.

The guides are written using Markdown. Markdown is a way to style text on the web. If you are not familiar with Markdown, check out this short article, Mastering Markdown (3 min read).

Thank you to our GitHub contributors…we’re always looking for more!

  • axelclark
  • Thebestbmxer
  • sheptig
  • JFetterAFX

Report a Bug (Error)

Bugs (errors) are tracked as GitHub issues. First, check the existing issues to see if someone has already reported the problem. If they have and the issue is still open, add a comment to the existing issue instead of opening a new one.

If there isn’t an existing issue, create a new issue. Explain the problem and include additional details to help maintainers of the project fix it.

Submit an Edit

If you see a way to improve a guide (e.g. fix typo or add a paragraph/link), you can submit a pull request which will tell the maintainers of the project you have a suggested improvement.

Each page in the site has a pull request link in the footer or sidebar which will start the process of creating a pull request from a fork to edit that page of the website.

Image from Gyazo

Make edits & submit commit:

Image from Gyazo

Create pull request:

Image from Gyazo

Once you submit the pull request, the maintainers will review, edit (if needed), and then push the change to the website.

Develop a guide on a new topic

If you would like to develop a new guide, first submit your suggestion as a new issue. The project maintainers will provide additional guidance.

Don’t worry if you aren’t familiar with Markdown, you can write your guide using Google Docs and convert it to Markdown, see below.

If you view any of the current guides in the docs folders on GitHub as “raw” you will see them written in Markdown, e.g. this page is contributing.md.

Here are the steps to create a new guide:

  1. Write the guide in Google Docs
    • You must use appropriate heading styles for the conversion software to work properly, e.g. in the Google Docs menu: Format -> Paragraph Styles -> Heading 1
  2. Convert your Google Docs text to Markdown using a Google Docs add-on called Docs to Markdown.
  3. Create a new file in the appropriate docs folder on Github. Name the file and add the .md file extension for Markdown.
  4. Paste your Markdown text into the new file.
  5. Click preview at the top of the GitHub editing window to see what your markdown will look like on the web. Make edits as needed.
  6. OPTIONAL: Add Jekyll front matter to the top of the guide for title and navigation. The project maintainers will add this if you’re not sure. For example:
     ---
     layout: default
     title: My New Guide
     parent: Spark Cell 101
     nav_order: 4
     ---
     # My New Guide
    
     This is how to...
    
  7. Submit change as a pull request. Click the big green propose new file button, review changes, then click the green create pull request button.