Thank you for your interest in contributing to the Southwest Concrete Paving Knowledge Base. This document provides guidelines and instructions for contributing content through GitHub.
-
Create a GitHub Account: If you don't already have a GitHub account, sign up here.
-
Familiarize Yourself with GitHub: If you're new to GitHub, take some time to understand the basics of Git and GitHub. GitHub's Quickstart Guide is a great resource.
-
Navigate to the Repository: Go to the Southwest Concrete Paving Knowledge Base repository.
-
Find the File You Want to Edit: The content is organized in Markdown files. Navigate to the specific file you want to update. The markdown files are located in the
docs
folder. -
Edit the File:
- Click the pencil icon (Edit this file) on the top right of the file view.
- Make your changes directly in the GitHub editor.
- You can use the
Preview
tab to check your changes.
After editing the content:
-
Scroll Down to 'Propose Changes':
- Add a brief but descriptive title for your changes.
- Optionally, add a more detailed description.
-
Click 'Propose Changes': This will create a new branch in the repository and take you to the 'Open a pull request' page.
-
Open a Pull Request:
- Review your changes.
- Click 'Create pull request'.
- This allows repository maintainers to review your changes before merging them into the main content.
-
Create a New File:
- In the appropriate directory within the
docs
folder, click 'Add file' and then 'Create new file'. - For example, to add a new file in the Equipment section: navigate to
docs/Equipment/
, then create your file (e.g.,new-equipment-guide.md
).
- In the appropriate directory within the
-
Write Your Content:
- Use Markdown to write your content. If you’re new to Markdown, here's a basic guide.
-
Save and Propose the New File:
- Name your file at the top (ensure it ends with
.md
). - Scroll down, add a commit message, and propose the new file.
- Name your file at the top (ensure it ends with
-
Edit
mkdocs.yml
:- Navigate to the root of the repository and open
mkdocs.yml
. - Click the pencil icon to edit.
- Navigate to the root of the repository and open
-
Add Your New File to the Navigation:
- In the
nav
section, add a link to your new Markdown file under the appropriate category. - Follow the existing format. For example:
- Equipment: - New Equipment Guide: Equipment/new-equipment-guide.md
- In the
-
Propose the Change:
- Scroll down, add a commit message, and propose the change.
-
Place Images in the Correct Directory:
- Images should be placed in an
Images
folder within the relevant section. - For example, for equipment-related images, use
docs/Equipment/Images/
.
- Images should be placed in an
-
Add Images to Your Markdown File:
- Use the Markdown syntax to add images. For example:
![Alt text for the image](Equipment/Images/your-image.jpg)
- Replace
your-image.jpg
with the name of your image file.
- Use the Markdown syntax to add images. For example:
-
Commit and Propose the Changes:
- After adding images to the
Images
folder and referencing them in your Markdown file, commit and propose these changes as described earlier.
- After adding images to the
After adding new content or making changes:
-
Follow the Same Process: As with editing content, scroll down to 'Propose changes', add a descriptive title and description, and create a pull request.
-
Review and Approval:
- The repository maintainers will review your pull request.
- If changes are approved, they will be merged into the main content.
Remember, quality and clarity are key in your contributions. If you’re adding new sections or significant content, consider discussing it with the team or the repository maintainers first.
- Clear and Concise Writing: Keep your contributions clear, concise, and factual.
- Check Grammar and Spelling: Ensure your text is free of errors.
- Stick to the Format: Follow the existing structure and formatting of the documents.
- Be Respectful and Constructive: When providing feedback on others' contributions, be respectful and constructive.
Markdown is a lightweight and easy-to-use syntax for styling text on the web. If you are not familiar with Markdown, here is a resource to get you started:
- Markdown Guide: A comprehensive guide to Markdown syntax, covering everything from basic to advanced usage.
We recommend familiarizing yourself with the basics of Markdown to ensure your contributions are formatted correctly.
If you have any questions or need assistance with the contribution process, please feel free to reach out to the repository maintainers.
Thank you for helping improve the Southwest Concrete Paving Knowledge Base!