GitHub Copilot can accelerate one of the hardest maintenance tasks in software engineering: understanding unfamiliar code and turning that understanding into useful documentation. In Visual Studio Code, Ask, Plan and Agent modes, inline chat, Quick Chat and smart actions can work at different scopes—from one selected line to an entire workspace. The key is to provide the right context, verify every explanation against the code and treat generated documentation as a draft that must remain technically accurate.
On this practical guide
Choose the right interaction surface
| Feature | Best use |
|---|---|
| Chat view | Multi-turn analysis, workspace questions and larger documentation tasks. |
| Inline Chat | Focused questions or edits directly beside selected code. |
| Quick Chat | Short questions that do not need a long conversation. |
| Explain smart action | Fast explanation of selected code or the active file. |
| Ask mode | Read-only exploration and drafting. |
| Plan mode | Design a documentation task before modifying files. |
| Agent mode | Create or update documentation across multiple files. |
Start by understanding the codebase
#codebase describe this project
Then ask:
- What are the main projects/modules?
- Which components are entry points?
- Where is persistence implemented?
- Which services contain business logic?
- What external systems are used?
- Where are tests located?
- Which files are configuration?
Compare the explanation with the repository. If Copilot misses an important component, add that file or folder explicitly as context.
Prompt quality determines explanation quality
| Weak prompt | Stronger prompt |
|---|---|
| What does this do? | Explain how the calculateTotal function handles discounts and invalid input. |
| Explain the project. | Using #codebase, describe the architecture, entry points, persistence layer and test projects. |
| Document this. | Document this public method with purpose, parameters, return value, exceptions and side effects. |
- Start with the goal.
- State the required output.
- Name the relevant files or scope.
- Define what must not be changed.
- Split a large documentation task into stages when needed.
Context keywords and references
#selection
#codebase
#terminalSelection
#terminalLastCommand
@vscode
@terminal
@github
/explain
/fix
/tests
Feature availability can vary by Visual Studio Code and Copilot version, so treat the supported keyword list and exact UI as version-sensitive.
Use #codebase when you do not know where the answer lives
#codebase is useful when a question spans the workspace. When the exact relevant files are already known, attaching them directly often produces a more focused response.
Explain one file or one block
File-level example
/explain Explain Program.cs.
Include:
- its responsibility
- important dependencies
- application startup flow
- external configuration
- risks or assumptions worth documenting
Selection-level example
/explain #selection
Explain:
- what this block does
- inputs and outputs
- side effects
- error paths
- assumptions
- what tests would validate it
Use Ask mode for analysis and drafting
- Summarise a module.
- Explain relationships between classes.
- Draft a README section.
- Identify missing documentation.
- Generate examples for review before insertion.
- Compare two implementation approaches.
Once the explanation is correct, copy it manually or move to a more autonomous mode.
Use Plan mode before broad documentation changes
Create a documentation plan for this repository.
Required outputs:
- README.md
- UsageExamples.md
- Architecture.md
- CHANGELOG.md
The plan should identify:
- source files to inspect
- sections to generate
- cross-links
- open questions
- verification steps
Do not edit files yet.
Use Agent mode for multi-file documentation
Create or update:
- README.md
- UsageExamples.md
- CHANGELOG.md
Requirements:
- derive content from #codebase
- link related documents
- cross-reference public classes and commands
- preserve existing manually written sections
- do not invent configuration values
- summarise all edits when finished
Review the diff, not only the final chat summary. Multi-file documentation can look coherent while still containing subtle inaccuracies.
Generate a useful README
- Project title.
- Description and purpose.
- Architecture or project structure.
- Installation.
- Usage.
- Configuration.
- Key classes/services or APIs.
- Testing.
- Contributing.
- License.
- Links to deeper documentation.
#codebase Generate a README.md draft.
Include:
- Description
- Project Structure
- Key Components
- Installation
- Usage
- Configuration
- Testing
- License
Use raw Markdown.
Do not invent commands or environment variables.
If information cannot be confirmed from the repository, mark it as TODO.
Generate inline documentation without creating noise
Inline documentation should explain information that is not obvious from good code.
- Public contract and intent.
- Non-obvious parameters.
- Return semantics.
- Exceptions.
- Side effects.
- Complex business rules.
- Performance or thread-safety constraints where relevant.
// BAD: increments i
i++;
// Better: document why the transition matters.
/// Advances to the next retry attempt.
/// The caller stops after MaxRetries to avoid an infinite recovery loop.
Ask mode for inline documentation
Suggest inline documentation for the selected class.
Document only:
- public class responsibility
- public methods
- non-obvious parameters
- return values
- documented exceptions
Do not comment trivial assignments or obvious control flow.
Plan + Agent for project-wide inline docs
Plan:
Add inline documentation to public C# APIs.
Rules:
- public classes, properties and methods only
- exclude test projects
- exclude generated code
- no comments that merely repeat names
- preserve existing documentation
- build after changes
Documentation for QA engineers
Testability
Ask where state, dependencies and side effects live before designing automation.
Risk discovery
Identify validation, authorisation and error paths that deserve negative tests.
Legacy systems
Explain unfamiliar modules before adding regression coverage.
API mapping
Trace controllers to services, repositories and external integrations.
Defect analysis
Use stack traces and related files as context to explain likely failure paths.
Test docs
Generate setup notes, suite descriptions and automation contribution guidance.
#codebase Trace the "return book" flow from user input to persistence.
For each step identify:
- class/method
- validation
- state change
- repository call
- possible failure
- observable output
- tests that currently cover it
Verify generated explanations
- Open every referenced class or method.
- Confirm method names and signatures.
- Check whether the described side effect really occurs.
- Verify configuration names.
- Run documented commands.
- Check that examples compile.
- Do not document behaviour that only exists in a test mock.
- Mark unknowns rather than letting AI invent an answer.
Keep documentation maintainable
| Problem | Better approach |
|---|---|
| README becomes huge | Keep overview in README and link specialised docs. |
| Generated comments repeat code | Document intent, constraints and contracts only. |
| Docs drift after changes | Include documentation updates in Definition of Done and PR review. |
| Agent rewrites manual content | State preservation rules explicitly in the prompt. |
| Examples become stale | Prefer executable or tested examples where practical. |
Documentation workflow
Understand code
↓
Confirm architecture
↓
Define documentation audience
↓
Plan required documents
↓
Generate draft
↓
Verify against code
↓
Run documented commands/examples
↓
Human review
↓
Commit with implementation
QA engineer checklist
- Use Ask mode before allowing broad documentation edits.
- Attach exact files when known.
- Use #codebase for cross-workspace questions.
- Make prompts specific about audience and required sections.
- Ask Copilot to mark unknown information rather than invent it.
- Review all generated file names, classes and commands.
- Run setup and usage commands from the documentation.
- Keep comments focused on intent and contracts.
- Exclude generated code and irrelevant test files from bulk tasks.
- Preserve useful human-written documentation.
- Update documentation in the same PR as behaviour changes.