Merge pull request #90 from github-samples/minor-updates

Improve documentation clarity and navigation with reference links

Author: GeekTrainer

content/1-hour/0-setup.md

@@ -1,11 +1,14 @@
 # Workshop setup
 
-To complete this workshop you will need to create a repository with a copy of the contents of this repository. While this can be done by [forking a repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo), the goal of a fork is to eventually merge code back into the original (or upstream) source. In our case we want a separate copy as we don't intend to merge our changes. This is accomplished through the use of a [template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository). Template repositories are a great way to provide starters for your organization, ensuring consistency across projects.
+| [← Getting started with GitHub Copilot][walkthrough-previous] | [Next: Coding with GitHub Copilot →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
+
+To complete this workshop you will need to create a repository with a copy of the contents of this repository. While this can be done by [forking a repository][fork-repo], the goal of a fork is to eventually merge code back into the original (or upstream) source. In our case we want a separate copy as we don't intend to merge our changes. This is accomplished through the use of a [template repository][template-repo]. Template repositories are a great way to provide starters for your organization, ensuring consistency across projects.
 
 The repository for this workshop is configured as a template, so we can use it to create your repository.
 
 > [!IMPORTANT]
-> Ensure you have the [requisite software](./README.md#required-local-installation) and [requisite resources](./README.md#required-resources) setup.
+> Ensure you have the [requisite software][required-software] and [requisite resources][required-resources] setup.
 
 ## Create your repository
 
@@ -51,8 +54,8 @@ With the repository created, it's now time to clone the repository locally. We'l
 
 The startup script will start two applications:
 
-- The backend Flask app on [localhost:5100](http://localhost:5100). You can see a list of dogs by opening the [dogs API](http://localhost:5100/api/dogs).
-- The frontend Astro/Svelte app on [localhost:4321](http://localhost:4321). You can see the [website](http://localhost:4321) by opening that URL.
+- The backend Flask app on [localhost:5100][flask-url]. You can see a list of dogs by opening the [dogs API][dogs-api].
+- The frontend Astro/Svelte app on [localhost:4321][astro-url]. You can see the [website][website-url] by opening that URL.
 
 ## Open your editor
 
@@ -65,6 +68,19 @@ With the code cloned locally, and the site running, let's open the codebase up i
 
 ## Summary and next steps
 
-You've now cloned the repository you'll use for this workshop and have your IDE setup! Next let's [add a new endpoint to the server](./1-add-endpoint.md)!
+You've now cloned the repository you'll use for this workshop and have your IDE setup! Next let's [add a new endpoint to the server][walkthrough-next]!
+
+
+| [← Getting started with GitHub Copilot][walkthrough-previous] | [Next: Coding with GitHub Copilot →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
 
-**NEXT:** [Exercise 1: Add an endpoint](./1-add-endpoint.md)
+[astro-url]: http://localhost:4321
+[dogs-api]: http://localhost:5100/api/dogs
+[flask-url]: http://localhost:5100
+[fork-repo]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+[required-resources]: ./README.md#required-resources
+[required-software]: ./README.md#required-local-installation
+[template-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
+[walkthrough-previous]: README.md
+[walkthrough-next]: ./1-add-endpoint.md
+[website-url]: http://localhost:4321

content/1-hour/1-add-endpoint.md

@@ -1,19 +1,23 @@
 # Coding with GitHub Copilot
 
-With code completion, GitHub Copilot provides suggestions in your code editor while you're coding. This can turn comments into code, generate the next line of code, and generate an entire function just from a signature. Code completion helps reduce the amount of boilerplate code and ceremony you need to type, allowing you to focus on the important aspects of what you're creating.
+| [← Workshop setup][walkthrough-previous] | [Next: Helping GitHub Copilot understand context →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
+
+
+With code completions, GitHub Copilot provides suggestions in your code editor while you're coding. This can turn comments into code, generate the next line of code, and generate an entire function just from a signature. Code completion helps reduce the amount of boilerplate code and ceremony you need to type, allowing you to focus on the important aspects of what you're creating.
 
 ## Scenario
 
 It's standard to work in phases when adding functionality to an application. Given that we know we want to allow users to filter the list of dogs based on breed, we'll need to add an endpoint to provide a list of all breeds. Later we'll add the rest of the functionality, but let's focus on this part for now.
 
-The application uses a Flask app with SQLAlchemy as the backend API (in the [/server](/server/) folder), and an Astro app with Svelte as the frontend (in the [/client](/client/) folder). You will explore more of the project later; this exercise will focus solely on the Flask application.
+The application uses a Flask app with SQLAlchemy as the backend API (in the [/server][server-code] folder), and an Astro app with Svelte as the frontend (in the [/client][client-code] folder). You will explore more of the project later; this exercise will focus solely on the Flask application.
 
 > [!NOTE]
 > As you begin making changes to the application, there is always a chance a breaking change could be created. If the page stops working, check the terminal window you used previously to start the application for any error messages. You can stop the app by using <kbd>Ctl</kbd>+<kbd>C</kbd>, and restart it by running `./scripts/start-app.sh`.
 
 ## Flask routes
 
-While we won't be able to provide a full overview of [routing in Flask](https://flask.palletsprojects.com/en/stable/quickstart/#routing), they are defined by using the Python decorator `@app.route`. There are a couple of parameters you can provide to `@app.route`, including the path (or URL) one would use to access the route (such as **api/breeds**), and the [HTTP method(s)](https://www.w3schools.com/tags/ref_httpmethods.asp) which can be used.
+While we won't be able to provide a full overview of [routing in Flask][flask-routing], they are defined by using the Python decorator `@app.route`. There are a couple of parameters you can provide to `@app.route`, including the path (or URL) one would use to access the route (such as **api/breeds**), and the [HTTP method(s)][http-methods] which can be used.
 
 ## Code completion
 
@@ -61,25 +65,38 @@ Let's build our new route in our Flask backend with the help of code completion.
         return jsonify(breeds_list)
     ```
 
-    > [!IMPORTANT]
-    > Because LLMs are probabilistic, not deterministic, the exact code generated can vary. The above is a representative example. If your code is different, that's just fine as long as it works!
+> [!IMPORTANT]
+> Because LLMs are probabilistic, not deterministic, the exact code generated can vary. The above is a representative example. If your code is different, that's just fine as long as it works!
 
 8. **Save** the file.
 
 ## Validate the endpoint
 
 With the code created and saved, let's quickly validate the endpoint to ensure it works.
 
-1. Navigate to [http://localhost:5100/api/breeds](http://localhost:5100/api/breeds) to validate the route. You should see JSON displayed which contains the list of breeds!
+1. Navigate to [http://localhost:5100/api/breeds][breeds-endpoint] to validate the route. You should see JSON displayed which contains the list of breeds!
 
 ## Summary and next steps
 
-You've added a new endpoint with the help of GitHub Copilot! You saw how Copilot predicted the next block of code you were likely looking for and provided the suggestion inline, helping save you the effort of typing it out manually. Let's start down the path of performing more complex operations by [exploring our project](./2-explore-project.md).
+You've added a new endpoint with the help of GitHub Copilot! You saw how Copilot predicted the next block of code you were likely looking for and provided the suggestion inline, helping save you the effort of typing it out manually. Let's start down the path of performing more complex operations by [exploring our project][walkthrough-next].
 
 ## Resources
 
-- [Code suggestions in your IDE with GitHub Copilot](https://docs.github.com/en/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot)
-- [Code completions with GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/ai-powered-suggestions)
-- [Prompt crafting](https://code.visualstudio.com/docs/copilot/prompt-crafting)
+- [Code suggestions in your IDE with GitHub Copilot][copilot-suggestions]
+- [Code completions with GitHub Copilot in VS Code][vscode-copilot]
+- [Prompt crafting][prompt-crafting]
+
+
+| [← Workshop setup][walkthrough-previous] | [Next: Helping GitHub Copilot understand context →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
 
-**NEXT:** [Exercise 2: Explore your project with Copilot](./2-explore-project.md)
+[breeds-endpoint]: http://localhost:5100/api/breeds
+[client-code]: /client/
+[copilot-suggestions]: https://docs.github.com/en/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot
+[flask-routing]: https://flask.palletsprojects.com/en/stable/quickstart/#routing
+[http-methods]: https://www.w3schools.com/tags/ref_httpmethods.asp
+[prompt-crafting]: https://code.visualstudio.com/docs/copilot/prompt-crafting
+[server-code]: /server/
+[vscode-copilot]: https://code.visualstudio.com/docs/copilot/ai-powered-suggestions
+[walkthrough-previous]: ./0-setup.md
+[walkthrough-next]: ./2-explore-project.md

content/1-hour/2-explore-project.md

@@ -1,5 +1,8 @@
 # Helping GitHub Copilot understand context
 
+| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Providing custom instructions →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
+
 The key to success when coding (and much of life) is context. Before we add code to a codebase, we want to understand the rules and structures already in place. When working with an AI coding assistant such as GitHub Copilot the same concept applies - the quality of suggestion is directly proportional to the context Copilot has. Let's use this opportunity to both explore the project we've been given and how to interact with Copilot to ensure it has the context it needs to do its best work.
 
 ## Scenario
@@ -8,7 +11,7 @@ Before adding new functionality to the website, you want to explore the existing
 
 ## Chat participants and extensions
 
-GitHub Copilot Chat has a set of available [chat participants](https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-participants) and [extensions](https://docs.github.com/en/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat) available to you to both provide instructions to GitHub Copilot and access external services. Chat participants are helpers which work inside your IDE and have access to your project, while extensions can call external services and provide information to you without having to open separate tools. We're going to focus on one core chat participant - `@workspace`.
+GitHub Copilot Chat has a set of available [chat participants][chat-participants] and [extensions][copilot-extensions] available to you to both provide instructions to GitHub Copilot and access external services. Chat participants are helpers which work inside your IDE and have access to your project, while extensions can call external services and provide information to you without having to open separate tools. We're going to focus on one core chat participant - `@workspace`.
 
 `@workspace` creates an index of your project and allows you to ask questions about what you're currently working on, to find resources inside the project, or add it to the context. It's best to use this when the entirety of your project should be considered or you're not entirely sure where you should start looking. In our current scenario, since we want to ask questions about our project, `@workspace` is the perfect tool for the job.
 
@@ -26,12 +29,21 @@ GitHub Copilot Chat has a set of available [chat participants](https://code.visu
 
 ## Summary and next steps
 
-You've explored context in GitHub Copilot, which is key to generating quality suggestions. You saw how you can use chat participants to help guide GitHub Copilot, and how with natural language you can explore the project. Let's see how we can provide even more context to Copilot chat through the use of [Copilot instructions](./3-copilot-instructions.md).
+You've explored context in GitHub Copilot, which is key to generating quality suggestions. You saw how you can use chat participants to help guide GitHub Copilot, and how with natural language you can explore the project. Let's see how we can provide even more context to Copilot chat through the use of [Copilot instructions][walkthrough-next].
 
 ## Resources
 
-- [Copilot Chat cookbook](https://docs.github.com/en/copilot/copilot-chat-cookbook)
-- [Use Copilot Chat in VS Code](https://code.visualstudio.com/docs/copilot/copilot-chat)
-- [Copilot extensions marketplace](https://github.com/marketplace?type=apps&copilot_app=true)
+- [Copilot Chat cookbook][copilot-cookbook]
+- [Use Copilot Chat in VS Code][copilot-chat-vscode]
+- [Copilot extensions marketplace][copilot-marketplace]
+
+| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Providing custom instructions →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
 
-**NEXT:** [Add Copilot instructions for additional context](./3-copilot-instructions.md)
+[chat-participants]: https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-participants
+[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/copilot-chat
+[copilot-cookbook]: https://docs.github.com/en/copilot/copilot-chat-cookbook
+[copilot-extensions]: https://docs.github.com/en/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat
+[copilot-marketplace]: https://github.com/marketplace?type=apps&copilot_app=true
+[walkthrough-previous]: ./1-add-endpoint.md
+[walkthrough-next]: ./3-copilot-instructions.md

content/1-hour/3-copilot-instructions.md

@@ -1,5 +1,8 @@
 # Providing custom instructions
 
+| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Add the filter feature →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
+
 There are always key pieces of information anyone generating code for your codebase needs to know - the technologies in use, coding standards to follow, project structure, etc. Since context is so important, as we've discussed, we likely want to ensure Copilot always has this information as well. Fortunately, we can provide this overview through the use of Copilot instructions.
 
 ## Scenario
@@ -21,8 +24,8 @@ Here are some guidelines to consider when creating a Copilot instructions file:
     - languages, frameworks and libraries in use.
     - required assets to be generated (such as unit tests) and where they should be placed.
     - any language specific rules such as:
-        - utilize [type hints](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html) in Python.
-        - use [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) rather than the `function` keyword in TypeScript.
+        - utilize [type hints][type-hints] in Python.
+        - use [arrow functions][arrow-functions] rather than the `function` keyword in TypeScript.
 - If you notice GitHub Copilot consistently provides an unexpected suggestion (e.g. using class components for React), add those notes to the instructions file.
 
 ## Create a Copilot instructions file
@@ -40,8 +43,8 @@ Let's create a Copilot instructions file. We'll start by asking Copilot to gener
 
 5. Note the function signature is similar to `def validate_dog_age(age)` without type hints.
 
-    > [!NOTE]
-    > Because LLMs are probabilistic rather than deterministic, the exact code will vary.
+> [!NOTE]
+> Because LLMs are probabilistic rather than deterministic, the exact code will vary.
 
 6. Create a new file in the **.github** folder called **copilot-instructions.md**.
 7. Add the markdown to the file necessary which provides information about the project structure and requirements:
@@ -77,8 +80,8 @@ Whenever you make a call to Copilot chat, the references dialog indicates all fi
     Create a Python function to validate dog age. Ensure age is between 0 and 20. Throw an error if it is outside this range.
     ```
 
-    > [!TIP]
-    > You can use up arrow to resend previous prompts to Copilot chat.
+> [!TIP]
+> You can use up arrow to resend previous prompts to Copilot chat.
 
 4. Note the references now includes the instructions file and provides information gathered from it.
 
@@ -90,15 +93,23 @@ Whenever you make a call to Copilot chat, the references dialog indicates all fi
     def validate_dog_age(age: int):
     ```
 
-    > [!NOTE]
-    > The exact code generated will vary, but the new Python suggestion should now utilize type hints.
+> [!NOTE]
+> The exact code generated will vary, but the new Python suggestion should now utilize type hints.
 
 ## Summary and next steps
 
-Copilot instructions improves the quality of suggestions, and ensures better alignment with the desired practices you have in place. With the groundwork in place, let's [add new functionality to our website](./4-add-feature.md)!
+Copilot instructions improves the quality of suggestions, and ensures better alignment with the desired practices you have in place. With the groundwork in place, let's [add new functionality to our website][walkthrough-next]!
 
 ## Resources
 
-- [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+- [Adding repository custom instructions for GitHub Copilot][custom-instructions]
+
+
+| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Add the filter feature →][walkthrough-next] |
+|:-----------------------------------|------------------------------------------:|
 
-**NEXT:** [Add a new feature to your website](./4-add-feature.md)
+[arrow-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
+[custom-instructions]: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
+[type-hints]: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
+[walkthrough-previous]: ./2-explore-project.md
+[walkthrough-next]: ./4-add-feature.md