How to Update the Wiki

This guide explains how to create and edit wiki pages. Every team member can contribute to keeping our wiki up-to-date!

Quick Start

There are three ways to update the wiki: 1. Web-based editing (easiest for small changes) 2. VSCode editing (best for larger changes or creating multiple pages) 3. GitHub Issues with Copilot (create an issue and let AI make the changes)

Method 1: Web-Based Editing (GitHub.com)

This is the fastest way to make small edits or fix typos.

Editing an Existing Page

  1. Navigate to the wiki page you want to edit on supernurds.com/wiki
  2. Click the pencil icon (✏️) in the top right corner of the page
  3. This will take you directly to the file on GitHub
  4. Click the pencil icon (Edit this file) on GitHub to enter edit mode
  5. Make your changes in the editor using Markdown syntax
  6. Scroll down to the "Commit changes" section
  7. Write a brief description of what you changed (e.g., "Fix typo in setup instructions")
  8. Choose one of the following:
  9. If you have write access: Select "Commit directly to the main branch" (for small fixes)
  10. If you don't have write access: Select "Create a new branch for this commit and start a pull request"
  11. Click "Commit changes" or "Propose changes"
  12. If you created a pull request, click "Create pull request" on the next page

Your changes will be reviewed and merged by a team lead!

Creating a New Page (Web)

  1. Go to the Wiki repository
  2. Navigate to the folder where you want to create the page (e.g., Software, Competition, etc.)
  3. Click "Add file" → "Create new file"
  4. Name your file with .md extension (e.g., New Guide.md)
  5. Add your content using Markdown syntax
  6. Follow steps 5-9 from "Editing an Existing Page" above

This method is better when you're creating multiple pages or making larger changes.

First-Time Setup

  1. Install Required Software:
  2. Visual Studio Code

  3. GitHub Desktop

  4. Clone the Wiki Repository:

  5. Follow the guide in Downloading GitHub Projects

  6. Clone the Wiki repository from FRCTeam3255/Wiki

  7. Open in VSCode:

  8. Right-click the Wiki folder in GitHub Desktop
  9. Select "Open in Visual Studio Code"

Making Changes in VSCode

  1. Open or Create a File:
  2. Navigate to the appropriate folder in the Explorer panel
  3. Open an existing .md file to edit

  4. Or create a new file: Right-click folder → "New File" → name it with .md extension

  5. Edit Your Content:

  6. Write your content using Markdown syntax

  7. VSCode will show a preview (press Ctrl+Shift+V on Windows or Cmd+Shift+V on Mac)

  8. Add Images (Optional):

  9. Take a screenshot and copy it to your clipboard
  10. In VSCode, paste the image (Ctrl+V or Cmd+V) where you want it
  11. The image will automatically be saved to the .images folder

  12. The correct markdown image link will be inserted

  13. Save Your Changes:

  14. Press Ctrl+S (Windows) or Cmd+S (Mac) to save

Committing and Pushing Your Changes

Once you're happy with your changes, you need to upload them to GitHub:

  1. Open GitHub Desktop:

  2. You should see your changed files listed

  3. Review Your Changes:

  4. Click on each file to see what changed

  5. Make sure everything looks correct

  6. Commit Your Changes:

  7. Write a brief summary in the "Summary" field (e.g., "Updated software setup guide")
  8. Optionally add more details in the "Description" field

  9. Click "Commit to main" (or your branch name)

  10. Push to GitHub:

  11. Click "Push origin" to upload your changes

  12. Create a Pull Request (if needed):

  13. If you're on a branch (not main), click "Create Pull Request"
  14. Fill out the description explaining your changes
  15. Click "Create pull request"

Note: Once your changes are merged into the main branch, the wiki website will automatically update within a few minutes!

Method 3: Using GitHub Issues with Copilot (Easiest - No Setup Required!)

This is the simplest method - describe what you want changed, assign the issue to GitHub Copilot, and it will make the changes for you!

Note: This requires GitHub Copilot to be enabled for the repository. Check with a team lead if you're unsure whether this is available.

When to Use This Method

  • You're not comfortable editing files directly
  • You want to suggest changes without learning Git or Markdown
  • You want to create new pages but prefer to describe what you need
  • You need multiple changes across different files

How to Create a Wiki Update Issue

  1. Go to the Issues Tab:
  2. Navigate to Wiki Issues

  3. Click "New issue"

  4. Describe Your Request:

  5. Title: Be specific (e.g., "Add guide for pneumatics" or "Update battery selection page")

  6. Description: Include as much detail as possible:

    • What page(s) need to be changed
    • What information needs to be added, updated, or removed
    • Any specific formatting or structure you want
    • Links to reference materials (if applicable)
    • Screenshots or examples (if helpful)

  7. Assign to Copilot:

  8. On the right sidebar, under "Assignees", click and type copilot to find the Copilot bot
  9. Select the Copilot assignee from the list

  10. Add relevant labels if needed (e.g., documentation, enhancement)

  11. Submit the Issue:

  12. Click "Submit new issue"

  13. Copilot will automatically start working on your request

  14. Review the Changes:

  15. Copilot will create a Pull Request with the changes
  16. You'll receive a notification when the PR is ready
  17. Review the changes and provide feedback if needed
  18. Once approved by a team lead, the changes will be merged and the wiki will update

Example Issue

Good Example: 

Title: Add guide for selecting pneumatic cylinders

Description:
Please create a new guide in the Mechanical folder that explains:
- How to choose the right pneumatic cylinder for different applications
- Common cylinder sizes used in FRC
- Stroke length considerations
- Force calculations
- Where to find cylinders in inventory

Include links to vendor websites and add images if possible.

Another Example: 

Title: Update Software Conventions page with new naming rules

Description:
On the Software/Conventions.md page, please add a new section about:
- Autonomous command naming: must start with "Auto_"
- Subsystem class naming: must end with "Subsystem"
- Constants file organization: one file per subsystem

Also update the example code to reflect these changes.

Tips for Good Issue Requests

  • Be Specific: The more detail you provide, the better the results
  • One Topic Per Issue: Create separate issues for different topics
  • Include Examples: Show what you want with examples or links
  • Provide Context: Explain why the change is needed
  • Check Existing Pages: Link to existing pages that should be updated

Markdown Basics

Markdown is a simple way to format text. Here are the most common elements:

Headings

# Main Heading (H1)
## Subheading (H2)
### Sub-subheading (H3)

Text Formatting

**bold text**
*italic text*
~~strikethrough~~

Lists

- Bullet point 1
- Bullet point 2
  - Sub-bullet

1. Numbered item 1
2. Numbered item 2
[Link text](https://example.com)
[Link to another wiki page](../Software/Conventions.md)

Images

![Image description](../.images/folder/image.png)

Code Blocks

```python
def hello():
    print("Hello, World!")
```

Tables

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Admonitions (Special Boxes)

!!! note "Title"
    This creates a highlighted note box.

!!! warning
    This creates a warning box.

!!! tip
    This creates a tip box.

File Organization

  • Place files in the appropriate folder based on topic:
  • Software/ - Programming guides and code documentation
  • Mechanical/ - Mechanical design and build guides
  • Electrical/ - Wiring, electrical components, and diagrams
  • Competition/ - Competition procedures and checklists
  • Build Season/ - Build season specific documentation
  • General/ - General team information and cross-functional guides
  • GitHub/ - GitHub and version control guides

  • etc.

  • Use clear, descriptive file names (e.g., Setting Up Driverstation.md)

  • Store images in .images/ folder (this happens automatically with VSCode paste)

Tips for Good Wiki Pages

  1. Be Clear and Concise: Write as if you're explaining to someone new
  2. Use Headings: Break content into sections with clear headings
  3. Add Screenshots: Images help clarify steps (especially for software guides)
  4. Include Context: Explain why something is done, not just how
  5. Keep it Updated: If you notice outdated information, fix it!
  6. Test Your Instructions: Try to follow your own guide to make sure it works

Getting Help

Review Process

All changes go through a review process:

  1. You create changes and submit a Pull Request
  2. Team leads review your changes
  3. If approved, changes are merged
  4. The wiki website automatically updates

This ensures all information is accurate and high-quality!