Update GitHub/Docs Onboarding

documentation/docs/intro.mdx

@@ -2,96 +2,153 @@
 sidebar_position: 1
 ---
 
+import Link from "@docusaurus/Link";
+
+
 # Project Documentation and Repository
 
-Documentation is a critical part of software projects. Think about it. When you're researching the tools you need for your projects, you're more likely to use the one that has documentation and a community that is actively using it. If you see a project on GitHub with no README file you're likely to just skip it, because you don't even know where to start. Large companies also expect you to document your code, so that management can add more team members when necessary, and so that 20 years down the road, they can maintain it.
+<div className={"col button_group"}>
+    <Link
+        className="button button--primary button--outline button--lg "
+        to="https://classroom.github.com/a/B0Pl5Vwl">
+        Create GitHub Team 🐙
+    </Link>
+</div>
+
+## Why Documentation Matters
+
+Documentation is a critical part of software projects. Think about it. When you're researching the tools you need for your projects, you're more likely to use the one that has documentation and a community that is actively using it. If you see a project on GitHub with no README file, you're likely to just skip it because you don't even know where to start. Large companies also expect you to document your code so that management can add more team members when necessary, and so that 20 years down the road, they can maintain it. For companies and open-source communities alike, documentation ensures:
+- Team scalability and onboarding
+- Long-term maintainability of the codebase
+- Clear communication of the project’s purpose and functionality
+
+Many modern projects use **Docusaurus**, an open-source tool by Meta, to build and maintain documentation. Docusaurus allows you to write documentation in simple Markdown files located in the `documentation/docs/` directory. If you’re new to Markdown, it’s easy to learn!
+
+---
+
+## Assignment Overview
+
+Your task is to create project documentation using Docusaurus and host it publicly on GitHub Pages.
+
+---
+
+## Documentation Requirements
+
+Your documentation should include the following:
+
+1. **Intro Page**
+- Name of the project
+- Authors
+- Release date
+- Version number
+
+2. **Table of Contents**
+(Auto-generated by Docusaurus)
+
+3. **Revision History**
+(Based on commit history)
+
+4. **Document Overview**
+- Summary of the document’s purpose and contents
 
-Many companies and open source projects are using a tool called Docusaurus, an open source tool for writing and maintaining documentation by Meta. Documentation is written in markdown files in the `documentation/docs/` directory. If you've never written Markdown before, it's incredibly easy.
+5. **Body**
+- Detailed content of the documentation
 
-## General Requirements of documentation
+6. **References**
+- Any external documents, publications, or resources used
 
-Documentation will contain:
--  Intro Page: showing the name of the document, authors, release date, and version
-number.
--  Table of Contents (auto generated by Docusaurus)
--  Revision History (generated from commit history)
--  Document overview: summarize the purpose and contents of the document
--  Body: the content of the document
--  References to other documents or publication
--  Glossary if required
+7. **Glossary** *(if applicable)*
+- Define any specialized terms used in the document
 
-All the figures and tables in your document must have captions accompanied with the figures
-and tables (you can use my [Figure component](/tutorial/custom-components/figure)). Provide reference list at the end of the document. You must cross-reference the
-captions and references in the body of the text in your documents.
+8. **Figures and Tables**
+- Include captions for all figures and tables
+- Cross-reference figures and tables in the document
+
+:::tip
+Use the provided [Figure component](/tutorial/custom-components/figure) to include captions with figures and tables.
+:::
+---
 
 ## Quick Markdown Tutorial
 
-Markdown is just a simple textfile that Docusaurus can interpret and convert into a pretty webpage.
+Markdown is a simple way to format text, and Docusaurus transforms it into a professional-looking website. Here’s an example:
 
 ```markdown
-# This is a heading 1
+# Heading 1
+## Heading 2
+### Heading 3
+```
 
-## This is a heading 2
+- **Heading 2** (##) appears in the right-hand sidebar as a table of contents.
+- **Heading 3** (###) appears as a sub-item under Heading 2.
 
-### This is a heading 3
-```
+For advanced Markdown features, visit the [Docusaurus tutorial section](/tutorial/intro) or [Docusaurus Markdown Features](https://docusaurus.io/docs/markdown-features).
 
-# This is a heading 1
+---
 
-## This is a heading 2
+## Setting Up the Project
 
-### This is a heading 3
+### Step 1: Join GitHub Classroom
 
-Heading 2 in Docusuarus appears in the right-hand sidebar as a table of contents with heading 3s as their children. For this class, that should largely be the only thing you need to know unless you want your documentation to look fancier. We will likely play around with some fancy features of docusaurus later in the semester. If you wish to learn more now you can go to the [docusaurus tutorial section](/tutorial/intro) of your documentation website, or go to [Docusaurus.io](https://docusaurus.io/docs/markdown-features) to view Markdown Features.
+1. [Click here to join the GitHub Classroom and get the starter project](https://classroom.github.com/a/B0Pl5Vwl).
+2. Log in to your GitHub account or create one at [GitHub](https://github.com).
+3. Select your name and TUmail from the list.
+4. Join your team or create a new one if none exists.
 
-## Setting up the project
+---
 
-Make sure each team member have their own GitHub account (we recommend you use your personal account for resume building). If you do not have one already create an account at https://github.com/ .
+### Step 2: Configure the GitHub Build Environment
 
-Each team member will get access to the team repo by using this GitHub Classroom link: https://classroom.github.com/a/HpJLFW02 (This will automatically associate your Github ID with your Canvas name, create a git repo for your team in the class Github organization and give the instructors and TA access).
-The first team member will have to create a team and give it a name. Other teams member will join this team.
+**One team member must complete this setup:**
 
-1. [Click here to join the GitHub Classroom and get the starter project.](https://classroom.github.com/a/HpJLFW02)
-2. Login to your GitHub Account
-3. Select your name and TUmail from the list.
-4. Select your team or create it if it's not listed.
-![Select a team or create a team](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/select-or-create-team.png)
+1. Generate a Personal Access Token:
+- Go to **Settings** → **Developer Settings** → **Personal Access Tokens** → **Generate new token**.
+- Select these permissions: `repo`, `workflow`, `admin:read:org`.
+- Set the expiration date to the course’s end.
+- Copy the token (you won’t be able to retrieve it later).
 
-### GitHub Build Environment Setup
+2. **Add the Token to the Repository:**
+- Navigate to the repository → **Settings** → **Secrets and Variables** → **Actions** → **New Repository Secret**.
+- Add the following secrets:
+- `TOKEN`: Your personal access token.
+- `USER`: Your GitHub username.
 
-In order for your Documentation Website to build you need to fill a few environment "Secrets" into the project. **ONLY ONE STUDENT HAS TO DO THIS!**
+3. **Enable GitHub Actions:**
+- Go to the **Actions** tab → Enable workflows.
 
-1. Click on your profile picture in the top right corner and click "Settings" in the dropdown.
-2. Scroll all the way to the bottom and on the left side click "Devleoper Settings"
-3. Click "Personal access tokens" then click "Generate new token" on the right.
-4. Select the following privileges and make the expiration date the date of the course end. (This is just for security purposes)
-![select token privileges repo, workflow, admin read:org](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/token-privlages.png)
-5. Copy your token to clipboard (make sure it's copied because it won't be retrievable when you leave the page.) ![Copy your token](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/copy-token.png)
-6. Go back to your project repository. Click the "Actions" tab then click the big green "I understand my workflows, go ahead and enable them" button.
-7. Click the settings tab. Now you're going to add the token you copied to the project. Click Secrets under Security > Secrets > Actions. Click new repository secret. Name the secret TOKEN and paste it.
-![Add TOKEN to project](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/add-token-to-project.png)
-You also need to make one last secret called USER which will contain your GitHub Username.
-8. Deploy the website. Edit the README Contributors section and push to main. GitHub Actions will take care of the rest.
-9. Once the job is complete navigate back to your repository's homepage (The Code Tab). You will see an Environments section that says "github-pages" with a 🚀. Click it. Then click "View deployment"
-![github-pages environment button](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/environments.png)
-10. Check out your new site!
-![Your website](https://raw.githubusercontent.com/Capstone-Projects-2022-Fall/project-instructors/main/documentation/static/img/site.png)
+4. **Deploy the Documentation Website:**
+- Edit the README file → Commit and push the changes to `main`.
+- GitHub Actions will build and deploy your site.
 
-### Repository and Site Cosmetics
+5. **View Your Website:**
+- Navigate to the repository homepage → Look for the “github-pages” environment → Click “View Deployment.”
 
-#### Edit the README file
-Edit the README.md file at the root of your repository. Include a project overview at the top.
+---
+
+### Step 3: Repository Setup
+
+1. Edit the `README.md` file:
+- Add a project overview at the top.
+2. Lock the `main` branch:
+- [Set up branch protection rules](https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule).
+
+---
+
+## Submission Instructions
 
+- Submit the link to your team’s repository after all members have joined.
+- Ensure all documentation requirements are complete.
 
+---
 
-- As a team, make sure to lock the main branch and require reviews for pull requests:
-https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule
+## Grading
 
-- You may as a team decide to make the repo private, consider keeping the repo public (optional). You should note, that your documentation will always be available publicly on GitHub Pages regardless.
+- This is a **group assignment**.
+- Graded as **Complete/Incomplete**.
+- Incomplete submissions will be invited for resubmission until all requirements are met.
 
-## For Submission
+---
 
-This is a group assignment. Submit a link to your newly created repository after all team members have joined.
+## Need Help?
 
-Grading
-This assignment is graded as complete or incomplete. Incomplete submissions will be invited to resubmit until all requirements are met.
+For questions or assistance, reach out to your [instructor or teaching assistant](/).

documentation/docs/requirements/Intro.md

@@ -18,4 +18,4 @@ The requirements specification document should contain the following sections:
 
 Revise the Project Proposal document template.
 
-A sample Requirements document [TempleCatsRequirementsDoc_13_2.docx](https://templeu.instructure.com/courses/114202/files/19367286?wrap=1)  provided here for your reference.
+Examples of Requirements Documents from previous semesters can be found [here](/showcase)