Update documentation to reflect GitHub Copilot's Plan mode and enhance clarity on features and usage

Author: ChrisHowd

learn-pr/wwl-azure/generate-documentation-using-github-copilot-tools/8-knowledge-check.yml

@@ -49,17 +49,17 @@ quiz:
     - content: "To provide feedback to the AI for future improvements."
       isCorrect: false
       explanation: "Incorrect. While feedback can be useful, the primary purpose of reviewing is to ensure the accuracy and completeness of the generated output."
-  - content: "How can GitHub Copilot Chat assist when encountering an error in the code?"
+  - content: "Which Chat view modes are available in GitHub Copilot for generating documentation?"
     choices:
-    - content: "It can explain the cause of the error and suggest ways to fix it."
-      isCorrect: true
-      explanation: "Correct. Copilot Chat can provide explanations for errors and suggest potential solutions."
-    - content: "It can prevent errors from occurring in the first place."
+    - content: "Ask, Edit, and Agent modes."
       isCorrect: false
-      explanation: "Incorrect. Copilot Chat assists in understanding and fixing errors, but it can't prevent them."
-    - content: "It can automatically fix the error without any user interaction."
+      explanation: "Incorrect. Edit mode is not one of the available Chat view modes. The three available modes are Ask, Agent, and Plan."
+    - content: "Ask, Agent, and Plan modes."
+      isCorrect: true
+      explanation: "Correct. The Chat view supports Ask, Agent, and Plan modes. Each mode has different strengths for documentation tasks. Ask mode is best for analyzing and previewing documentation. Agent mode is best for multi-file documentation generation. Plan mode creates a detailed implementation plan that can be handed off to agent mode."
+    - content: "Only Ask and Agent modes."
       isCorrect: false
-      explanation: "Incorrect. While Copilot Chat can suggest fixes, it doesn't automatically apply them."
+      explanation: "Incorrect. In addition to Ask and Agent modes, the Chat view also supports Plan mode, which creates implementation plans that can be handed off to agent mode for execution."
   - content: "What is the primary purpose of project documentation in software development?"
     choices:
     - content: "To provide a detailed codebase for developers to use."
@@ -71,17 +71,17 @@ quiz:
     - content: "To provide essential information for understanding the project's scope and purpose."
       isCorrect: true
       explanation: "Correct. Project documentation provides essential information for understanding the project's scope, purpose, constraints, dependencies, and requirements."
-  - content: "How can GitHub Copilot Chat be used in the context of project documentation?"
+  - content: "What is a key advantage of using agent mode to generate project documentation?"
     choices:
-    - content: "To generate specific sections of the project documentation, such as the project overview, requirements, constraints, dependencies, and summary."
+    - content: "Agent mode can analyze the entire project structure and generate documentation that links and summarizes content across the codebase."
       isCorrect: true
-      explanation: "Correct. GitHub Copilot Chat can be used to generate specific sections of the project documentation."
-    - content: "To communicate with the project stakeholders and gather their requirements."
+      explanation: "Correct. Agent mode can gather information from multiple files and folders, describe complex relationships, include links between documents, and execute batch documentation tasks such as creating README, UsageExamples, and ChangeLog files."
+    - content: "Agent mode provides only high-level overviews of individual files."
       isCorrect: false
-      explanation: "Incorrect. GitHub Copilot Chat isn't designed for communication with stakeholders."
-    - content: "To automatically write the entire codebase for the project."
+      explanation: "Incorrect. Agent mode can analyze the entire project structure and generate detailed documentation across multiple files, not just individual file overviews."
+    - content: "Agent mode requires the @workspace chat participant to analyze the codebase."
       isCorrect: false
-      explanation: "Incorrect. GitHub Copilot Chat can assist with code suggestions, but it doesn't write the entire codebase."
+      explanation: "Incorrect. Chat participants like @workspace aren't available in agent mode. You can add context using #codebase and the Attach Context button instead."
   - content: "What is the purpose of generating inline code documentation in software development?"
     choices:
     - content: "To make the code more complex and challenging for other developers."
@@ -93,14 +93,14 @@ quiz:
     - content: "To increase the size of the codebase."
       isCorrect: false
       explanation: "Incorrect. While documentation does add to the size of the codebase, its primary purpose is to improve readability and maintainability, not to increase size."
-  - content: "How can GitHub Copilot Chat help generate inline code documentation?"
+  - content: "What is the purpose of the Plan mode in GitHub Copilot Chat?"
     choices:
-    - content: "By automatically writing the entire codebase."
+    - content: "To directly apply code changes to files without user review."
       isCorrect: false
-      explanation: "Incorrect. GitHub Copilot Chat assists in generating inline code documentation, not in writing the entire codebase."
-    - content: "By generating inline code comments based on natural language prompts or commands."
+      explanation: "Incorrect. Plan mode doesn't directly apply changes. It creates an implementation plan that can be reviewed and then handed off to agent mode for execution."
+    - content: "To create a detailed implementation plan that can be handed off to agent mode for execution."
       isCorrect: true
-      explanation: "Correct. GitHub Copilot Chat can generate inline code comments based on natural language prompts or the '/doc' command."
-    - content: "By providing real-time chat support with other developers."
+      explanation: "Correct. Plan mode analyzes the codebase, identifies requirements, and produces a step-by-step plan. Once approved, you can select Start Implementation to hand off the plan to agent mode, or select Open in Editor to save the plan as a Markdown file."
+    - content: "To provide inline code suggestions directly in the editor."
       isCorrect: false
-      explanation: "Incorrect. GitHub Copilot Chat doesn't provide real-time chat support with other developers. It generates inline code documentation."
+      explanation: "Incorrect. Plan mode doesn't provide inline suggestions. It creates implementation plans in the Chat view that can be handed off to agent mode or saved as a Markdown file for later use."

learn-pr/wwl-azure/generate-documentation-using-github-copilot-tools/includes/1-introduction.md

@@ -14,7 +14,7 @@ After completing this module, you’ll be able to:
 
 - Describe how GitHub Copilot uses natural language processing and machine learning to interpret user prompts and provide relevant responses.
 - Use GitHub Copilot to brainstorm new apps or features, explore coding tools and techniques, evaluate issues and potential fixes, and explain complex or unfamiliar code.
-- Generate project documentation using GitHub Copilot's Ask, Edit, and Agent modes.
+- Generate project documentation using GitHub Copilot's Ask, Agent, and Plan modes.
 - Generate inline code documentation using GitHub Copilot's Chat view, Inline chat, and Smart actions.
 - Complete a lab exercise that involves using GitHub Copilot to analyze and document a codebase.
 

learn-pr/wwl-azure/generate-documentation-using-github-copilot-tools/includes/2-review-github-copilot-explain-document-features.md

@@ -18,7 +18,7 @@ The following GitHub Copilot features can be used to generate inline code docume
 
 - Ask mode: Use the ask mode to suggest inline code documentation for a code file, class, or method. Review the suggested inline documentation in the Chat view. Request updates as needed in the chat conversation. Once you're satisfied with the proposed documentation, you can insert the suggested documentation into the corresponding code file.
 
-- Edit mode: Use the edit mode to suggest inline code documentation for a code file, class, or method. Review the suggested documentation in the editor, navigating between suggested updates. Accept or reject individual suggestions, or modify suggestions as needed.
+- Plan mode: Use the Plan mode to create a detailed implementation plan for your documentation tasks. The Plan mode can be used to analyze the codebase, identify documentation requirements, and produce a step-by-step plan. Once the plan is approved, you can hand it off to agent mode for execution.
 
 - Agent mode: Use the agent mode to autonomously generate inline code documentation for specified code projects, files, classes, or methods. Have the agent perform other tasks during or after the documentation process. Accept or reject the updates when the agent has completed the assigned tasks.
 
@@ -32,12 +32,12 @@ The following GitHub Copilot features can be used to generate project documentat
 
 - Chat view in ask mode: Use the ask mode to analyze the codebase and gain an understanding of the code projects, files, and classes. Use ask mode to preview suggested project documentation. Review suggestions and request updates or other details as needed. Insert the suggested documentation into a project documentation file (README.md).
 
-- Chat view in Edit mode: Generate a project documentation file (README.md).
+- Chat view in Plan mode: Create a detailed implementation plan for project documentation, then hand off to agent mode for execution.
 
 - Chat view in agent mode: Generate a collection of project documentation files: create/update the README.md, create/update the UsageExamples.md, and create/update the ChangeLog.md. Include links between the documentation files, cross-reference classes and methods, and ensure consistency across docs.
 
 > [!IMPORTANT]
-> When you use the Chat view in agent mode, GitHub Copilot may make multiple premium requests to complete a single task. Premium requests can be used by user-initiated prompts and follow-up actions Copilot takes on your behalf. The total premium requests used will depend on the complexity of the task, the number of steps involved, and the model selected.
+> When you use the Chat view in agent mode, each prompt you enter counts as one premium request, multiplied by the model's multiplier. GitHub Copilot may take several follow-up actions to complete your task, but these follow-up actions don't count toward your premium request usage. Only the prompts you enter are billed. The total premium requests used depends on how many prompts you enter and the model selected. The Free Plan for GitHub Copilot gets 50 premium requests per month. Check plan descriptions for more details about premium request limits for each GitHub Copilot subscription.
 
 ## Summary
 

learn-pr/wwl-azure/generate-documentation-using-github-copilot-tools/includes/3-examine-github-copilot-prompts-keywords.md

@@ -18,26 +18,26 @@ GitHub Copilot uses the following keywords to help you specify the context and i
 
 - Chat participants: Chat participants are like experts in a specific field that help GitHub Copilot generate better responses. Chat participants are specified using the `@` symbol.
 
-- Slash commands: Slash commands help to describe the intent (the goal or objective) of your prompt. One of Copilot Chat's tasks when answering questions is to determine the intent, understanding what you want to do. Slash commands can help clarify your intent.
+- Slash commands: Slash commands help to describe the intent (the goal or objective) of your prompt. One of GitHub Copilot Chat's tasks when answering questions is to determine the intent, understanding what you want to do. Slash commands can help clarify your intent.
 
 - Chat variables: Chat variables provide domain-specific context. You can reference a chat variable in your chat prompt by using the `#` symbol. By using a chat variable, you can be more specific about the context that you include in your chat prompt.
 
 ### Chat participants
 
 GitHub Copilot Chat provides better responses when it understands the context that you're interested in and can apply the best resources. You can help GitHub Copilot Chat generate better responses by adding a Chat participant to your prompts. Chat participants are like experts in a specific field that provide better responses. Chat participants are specified using the `@` symbol.
 
-Currently, Copilot Chat supports the following built-in chat participants:
+Currently, GitHub Copilot Chat supports the following built-in chat participants:
 
 - `@workspace`: The `@workspace` participant can help answer questions about the code in your workspace or suggest ways to refactor or improve your code.
 - `@vscode`: The `@vscode` participant knows about commands and features in the Visual Studio Code editor itself, and can help you use them.
 - `@terminal`: The `@terminal` participant can help with the integrated terminal shell and its contents.
 - `@github`: The `@github` participant can help get answers grounded in web search, code search, and your enterprise's knowledge bases.
 
-You can prefix your prompt with a specific chat participant to help Copilot generate a more relevant response.
+You can prefix your prompt with a specific chat participant to help GitHub Copilot generate a more relevant response.
 
 ### Slash commands
 
-Slash commands help Copilot Chat understand your intent when you ask a question. Are you learning about a code base (`/explain`), do you want help with fixing an issue (`/fix`), or are you creating test cases (`/tests`)? By letting Copilot Chat know what you're trying to do, it can tune its reply to your task and provide helpful commands, settings, and code snippets.
+Slash commands help GitHub Copilot Chat understand your intent when you ask a question. Are you learning about a code base (`/explain`), do you want help with fixing an issue (`/fix`), or are you creating test cases (`/tests`)? By letting GitHub Copilot Chat know what you're trying to do, it can tune its reply to your task and provide helpful commands, settings, and code snippets.
 
 Chat participants are often bundled with slash commands. The slash command is a concise way to explain your intent to the chat participant. The `/explain` slash command is often bundled with the `@workspace` chat participant. The combination of a chat participant and a slash command is a powerful way to clarify your intent.
 
@@ -110,7 +110,7 @@ About the `#codebase` keyword:
 
 - The `#codebase` keyword is a tool that performs a codebase search based on the user prompt and adds the relevant code as context to the chat prompt.
 - When you use the `#codebase` keyword, the language model remains in control and can combine `#codebase` with other tools for editing scenarios.
-- The `#codebase` keyword can be used in all chat modes (Ask, Edit, and Agent).
+- The `#codebase` keyword can be used in all chat modes (Ask, Agent, and Plan).
 - Examples: "`add a tooltip to this button, consistent with other button #codebase`", "`add unit tests and run them #codebase`"
 
 GitHub recommends using `#codebase` in your chat prompts, as it provides more flexibility.