Build knowledge from a help desk ticket.
You are going to complete a small, safe version of the same workflow used to turn support work into reusable knowledge. You do not need GitHub experience. This guide stays open and tells you exactly what to do next.
A workstation user reports that websites will not load. The incident has enough evidence for us to document a safe troubleshooting path.
Time: about 35–45 minutes
Format: instructor-led
Goal: submit a practice Knowledge Article pull request
This is fictional classroom work. Do not use real credentials, student records, private tickets, internal network details, or private screenshots. Classroom participation does not grant SOTE infrastructure authority.
Keep the guide. Open the workspace.
Use two browser tabs today. Keep this SOTE training page open. The portal is your guide. GitHub is your workspace.
Open GitHub in a new tab, sign in with your own account, then return here. Do not start clicking around yet.
Open GitHub in a new tab ↗You should never have to leave the instructions behind in order to complete the task.
Meet the repository.
Now enter the CIT-205 classroom workspace directly.
Open the CIT-205 Classroom repository. Find the repository name near the top of the page and notice the Public label. Then return here.
Open CIT-205 Classroom ↗A repository is a project's workspace. It contains files, folders, instructions, and the history of changes.
Follow the trail to a file.
You do not need to memorize GitHub. You only need to understand where you are.
Open the knowledge folder. Then open examples. Then open the no-display Knowledge Article. Watch the path above the file change as you move.
Open the Knowledge folder ↗That path is your breadcrumb trail. Selecting a name in the path moves you back toward the repository front door.
Read knowledge like a technician.
Before writing anything, inspect a finished classroom example.
Open the worked article. With the class, identify four things: the reported problem, one question to ask, one safe troubleshooting step, and one reason to stop and escalate.
Open worked example ↗Another technician can act from it without needing the original technician standing beside them.
Read the ticket evidence.
Here is the entire training ticket. You do not need to search for another document.
Environment: fictional classroom Windows workstation using a wired network connection.
What changed: the desk area was cleaned and cables were moved earlier that morning.
Observed evidence: the workstation powers on normally. The network icon shows a wired connection. Nearby classroom workstations can reach websites.
Safe checks already performed: the Ethernet cable is visibly connected at the workstation. No equipment has been opened, reset, or reconfigured.
Training resolution evidence: after reseating the accessible Ethernet connection at the workstation, network access returned. A test website loaded successfully.
Document only what the evidence supports. Do not invent a root cause that was never proven.
Turn evidence into technician guidance.
Before touching GitHub, decide what belongs in the article.
Identify:
- two clarification questions you would ask the user;
- the safest first observable check;
- what action appears to have restored service;
- how you would verify the problem is resolved;
- one condition that should cause a technician to stop and escalate.
“Reseating the connection restored service” is supported. “The cable was definitely loose” is not proven. Good documentation separates evidence from assumption.
Convert the Word draft for GitHub.
Your real Knowledge Article starts in Word. GitHub does not automatically turn Word formatting into Markdown, so before publishing you convert the structure into simple Markdown marks.
In Word, open the finished article, choose Select All, and copy the text. When pasted into a plain-text editor, most visual formatting such as heading size and bold styling may disappear.
- Put
#before the article title. - Put
##before each section heading. - Wrap labels that should stay bold in
**double asterisks**. - Use
-for bullet points. - Use
1.,2.,3.for ordered troubleshooting steps. - Leave a blank line between headings, paragraphs, and lists so GitHub renders them cleanly.
Word heading: Problem and Symptoms
Markdown heading: ## Problem and Symptoms
Word label: Status: Student Draft
Markdown label: **Status:** Student Draft
The conversion has already been completed below so we can focus on learning the GitHub workflow. Read the Markdown and notice how it maps to the Word structure. Later, your own article will follow this same conversion process.
# Workstation Connected but Websites Will Not Load **Status:** Student Draft — not approved operational guidance **Scenario:** ACE-TRAIN-001 **Applies to:** Fictional classroom Windows workstation using a wired network connection ## Problem and Symptoms The user reports that the workstation appears connected to the network, but websites will not load. Nearby classroom workstations can reach websites. ## Questions to Ask - When did the problem begin? - Did anything change or move around the workstation before the problem started? ## Before You Begin Obtain permission before moving cables or interrupting the user's work. Do not open equipment, reset network hardware, or change network configuration during this classroom exercise. ## Troubleshooting Steps 1. Confirm the workstation powers on normally. 2. Observe the network status shown by the workstation. 3. Compare the symptom with another nearby classroom workstation. 4. Visually inspect the accessible Ethernet connection at the workstation. 5. If permitted, reseat the accessible Ethernet connection without forcing or removing secured equipment. 6. Test access to an instructor-approved website. ## Likely Resolution Network access returned after the accessible Ethernet connection at the workstation was reseated. The evidence does not prove why the connection failed. ## Verification Confirm that the workstation can load an instructor-approved website and that the user can resume normal network use. ## Stop and Escalate Stop if equipment appears damaged, a step requires elevated permission, network configuration changes are required, or the safe checks do not restore access. Record the symptoms, checks, and results for the next technician. ## Sources and Related Knowledge - ACE-TRAIN-001 classroom training scenario ## Revision Notes - Initial guided-mission student draft.
Create your fork without changing the setup.
A fork is your personal GitHub copy of the classroom repository. GitHub will show you a setup page before it creates the fork. We are going to check every field before you press the button.
Open the fork page in your GitHub tab. If GitHub tells you that you already have a fork, open your existing fork instead and skip to the checkpoint at the bottom of this step.
Open the fork setup page ↗At the top of the fork setup page, find Owner. Leave it set to your own GitHub account. Do not choose the SOTE organization or any other account.
Find Repository name. Leave it exactly as CIT-205-classroom. Do not rename it.
GitHub may show the classroom repository description. Do not rewrite or remove it. Leave the description as it appears.
Scroll down until you see the option to copy the main branch only. Leave that option checked. Do not turn it off. For this class, we want your fork to begin as a clean copy of the current classroom main branch.
After you have checked the owner, repository name, description, and main-branch option, scroll to the bottom and choose Create fork. Wait for GitHub to finish creating your copy.
On the repository front page, look for the line Forked from student-operated-technology-ecosystem/CIT-205-classroom. That confirms you are in your personal fork rather than the official classroom repository.
Stop here and ask before changing anything else. Do not rename the repository, switch owners, change the description, or alter the branch-copy option to make the screen “look right.”
Your fork is your copy of the classroom repository. Working there protects the official copy while you build a proposed contribution.
Create a branch for this article.
You are on the front page of your fork. The branch button just above the file list currently says main.
Tap the branch button labeled main.
If GitHub shows a search field, tap inside it. If it shows View all branches first, open that.
Replace YOUR-GITHUB-USERNAME with your actual GitHub username, then type the full branch name. Example: if your username is jrivera, use article/jrivera-training-network. Because the branch does not exist yet, GitHub should offer Create branch or Create branch from main. Choose that option.
After GitHub creates the branch, the same branch button should now begin with article/.
Confirm GitHub still shows Forked from student-operated-technology-ecosystem/CIT-205-classroom and the branch button begins with article/. If it still says main, select the article branch before continuing.
The fork is your workspace. The branch isolates this one proposed change inside that workspace.
Add your Knowledge Article.
This step has two parts: create the file name, then put the article text inside the file before you commit it.
- Open knowledge, then student-articles.
- On mobile, tap the three-dot menu (•••) to the right of the branch selector.
- Choose Create new file. If GitHub shows an Add file submenu first, choose Add file → Create new file.
In the filename box, enter KA-YOUR-GITHUB-USERNAME-training-network.md.
After entering the filename, stay on this page and scroll down. The large text area below the filename is the file editor. That is where the Knowledge Article goes.
Return to this training tab and press the button below.
Switch back to GitHub. Tap inside the large editor area beneath the filename and paste. You should now see the article beginning with # Workstation Connected but Websites Will Not Load.
Do not press Commit changes yet.
Use GitHub's Preview tab to confirm the article renders with headings, lists, and sections instead of appearing as one empty file.
You should be on your article/... branch, and the article should appear correctly in Preview. If the editor is blank or the Preview is empty, stop here. Do not commit an empty file.
After the Preview looks correct, choose Commit changes…. This does not finish the process yet. It opens GitHub's commit confirmation window. Leave that window open and return to this guide for the next step.
After you type the filename, the editor may be farther down the page than you expect. Scroll below the filename field before looking for the commit button.
Open that .md file. On mobile, the edit command may be hidden in the three-dot menu (•••) on the file toolbar, to the right of Preview / Code / Blame. Open that menu and choose the edit option, then paste the article and commit the correction to the same article/... branch.
Edit is where the Markdown text lives. Preview shows how that text will look when GitHub renders the article.
Commit the article to your branch.
A commit records a saved version of your change. GitHub now opens a confirmation window. Check each part before saving.
Replace GitHub's automatic message with Add ACE-TRAIN-001 knowledge article.
This field is optional for this mission. Leave it blank.
Select the first option: Commit directly to the article/... branch. You already created this branch for the Knowledge Article, so this is where the file belongs.
Do not select Create a new branch for this commit and start a pull request. That option is useful when you have not created a working branch yet. In this mission, it would create an unnecessary second branch.
The first radio button should be selected, and the branch shown there should be the same article/... branch you created earlier.
Choose the green Commit changes button.
Your new .md file should appear inside knowledge/student-articles/ while your article/... branch is selected.
We are separating the workflow on purpose: save the file to your article branch first, inspect the saved work, and then use the next step to propose that branch for review.
Open a pull request.
Your article is now saved on your branch. GitHub should show that your branch is ahead of the classroom repository and invite you to open a pull request.
Select CIT-205-classroom in GitHub's path near the top so you are back at the repository front page.
On mobile, find the Contribute button. Tap it. GitHub should open a panel that says your branch is ahead of student-operated-technology-ecosystem/CIT-205-classroom:main.
The panel should name your article/... branch and say it is ahead of student-operated-technology-ecosystem/CIT-205-classroom:main. This means GitHub sees changes in your branch that are not yet in the classroom repository.
Tap the green Open pull request button in that panel. This takes you to GitHub's comparison and pull-request screen.
Before typing anything, confirm the base repository is student-operated-technology-ecosystem/CIT-205-classroom with base branch main, and the head repository is your fork with your article/... branch selected.
You should be proposing your article branch → classroom main. If those are reversed, stop and ask before continuing.
For this guided mission, you are not inventing a new article or a new scenario. You are submitting the practice article you just created from ACE-TRAIN-001 so you can learn the pull-request workflow.
- Title it
ACE-TRAIN-001 Knowledge Article — YOUR NAME. - Under Scenario and Purpose, write:
ACE-TRAIN-001 is a fictional classroom network-connectivity scenario. This article gives a technician a safe, evidence-based sequence for checking and verifying the workstation connection. - Under Evidence and Assumptions, write:
The scenario states that nearby workstations have network access and that service returned after the accessible Ethernet connection was reseated. The exact root cause was not proven, so the article does not claim that the cable was definitely loose or faulty. - Check each Safety and Privacy item only after confirming it is true. If the boxes are not clickable while you are creating the pull request, switch to the Write tab and change each verified item from
[ ]to[x], then return to Preview to confirm the checkmarks appear. - Under Review Requested, write:
Please review the Troubleshooting Steps and Stop and Escalate sections for clarity and safety.
In a later real assignment, you will replace these training responses with details from your own Word draft and your own assigned scenario.
Review the changed file list. It should contain only your training Knowledge Article. Then choose Create pull request.
A pull request does not change the official repository by itself. It asks for your branch to be reviewed before anything is merged into the classroom copy.
What happens to your pull request now?
Creating the pull request does not publish the article into the classroom Knowledge Base. It moves the article into review.
A classmate reads the rendered article, then uses Files changed to attach feedback to exact lines. The reviewer proposes improvements; the reviewer does not directly rewrite your branch.
You edit the article on the same article/... branch and commit the revision. The open pull request updates automatically, so the discussion and revision history stay together.
The instructor checks the article, peer feedback, and your revision. If it is ready for classroom use, the instructor merges the pull request into the classroom repository's main branch.
After the merge, the article becomes part of the shared CIT-205 Classroom Knowledge Base. That means it is accepted for classroom learning. It does not automatically become official SOTE operational guidance.
A strong classroom article can later be reviewed, adapted, and promoted into the governed SOTE infrastructure Knowledge Base. That promotion is a separate decision. Classroom acceptance is the proving ground; SOTE canon is the operational publication layer.
You proposed a new Knowledge Article.
Look at your open pull request and select Files changed. Confirm that the proposal contains only your training Knowledge Article.
You did not publish directly into shared knowledge. You proposed a change, preserved its history, and created a review point before anything can enter the classroom Knowledge Base.