Copilot Chat Cookbook Deep Dive: Document Code

Dhanoop Bhaskar June 29, 2026 copilot

Why this category matters

Documentation quality controls long-term team velocity. The cookbook shows how to use Copilot Chat to move from raw code and repository history to clear, current, and reusable technical communication.

Use cases

  • Maintainers improving documentation quality at scale
  • Developers onboarding into unfamiliar codebases
  • Developers learning to generate documentation that stays accurate over time

The 6 examples in this category

  1. Creating issues
  2. Documenting legacy code
  3. Explaining legacy code
  4. Explaining complex algorithms or logic
  5. Syncing documentation with code changes
  6. Writing discussions or blog posts

Diagram: Documentation lifecycle with Copilot Chat

+-------------------------------+
| Code, issues, PRs, discussions|
+-------------------------------+
               |
               v
+-------------------------------+
| Prompt for explanation/draft  |
| - audience                    |
| - format                      |
| - scope                       |
+-------------------------------+
               |
               v
+-------------------------------+
| Generated artifact            |
| - issue draft                 |
| - comments/docs               |
| - blog/discussion draft       |
+-------------------------------+
               |
               v
+-------------------------------+
| Human review and publish      |
+-------------------------------+

1) Creating issues

Cookbook scenario:

  • Generate an issue draft for API endpoint validation with labels and acceptance criteria.

Prompt pattern:

In <owner>/<repo>, create an issue to add server-side validation for createUser.
Include middleware example. Label it with backend and enhancement.

What to review before submitting:

  • Problem statement is specific.
  • Proposal includes implementation direction.
  • Acceptance criteria are testable.
  • Labels and scope match repository conventions.

2) Documenting legacy code

The goal here is to add inline comments to undocumented source code so maintainers can read it without needing to mentally parse every line. The cookbook example uses COBOL.

Source code to document:

IDENTIFICATION DIVISION.
PROGRAM-ID. CALC-TAX.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
  01 GROSS-INCOME     PIC 9(7)V99.
  01 TAX-AMOUNT       PIC 9(7)V99.
  01 TAX-RATE         PIC V99 VALUE 0.25.
PROCEDURE DIVISION.
  COMPUTE TAX-AMOUNT = GROSS-INCOME * TAX-RATE
  STOP RUN.

Prompt pattern:

Comment this code thoroughly. Explain the purpose of each division, variable, and computation.

A good response attaches intent to every section: what WORKING-STORAGE holds, why PIC 9(7)V99 is a fixed-point decimal, and what the computation actually does in business terms ("25% flat tax on gross income").

Review checklist:

  • Comments explain intent, not just syntax.
  • Risky sections (transactions, error paths) are clearly documented.
  • Terminology is consistent with domain language.

3) Explaining legacy code

The goal here is onboarding — helping a developer unfamiliar with the language build a mental model quickly. This is different from documenting: you are not adding comments to the file, you are getting a conversational explanation with analogies drawn from a language you already know.

Same source, different goal:

IDENTIFICATION DIVISION.
PROGRAM-ID. CALC-TAX.
PROCEDURE DIVISION.
  COMPUTE TAX-AMOUNT = GROSS-INCOME * TAX-RATE
  STOP RUN.

Prompt pattern:

I am a Python developer. Help me understand this COBOL code. Please provide analogies.

A good response maps COBOL divisions to Python concepts: PROCEDURE DIVISION is the function body; WORKING-STORAGE is module-level variable declarations; COMPUTE is a simple assignment. The analogy makes the structure immediately navigable for someone without prior COBOL exposure.

Why the distinction matters: documenting modifies the artifact; explaining is a read-only conversation. Use documenting when you want persistent inline comments; use explaining when you need to understand first before touching anything.

4) Explaining complex algorithms or logic

Cookbook scenario:

  • Add comments to async retry logic with cancellation and UI status updates.

Prompt pattern:

Add comments to this code to make it more understandable.

Review checklist:

  • Retry/backoff behavior is explained accurately.
  • Cancellation and exception behavior are described correctly.
  • Threading/UI update constraints are documented.

5) Syncing documentation with code changes

Cookbook scenario:

  • Update outdated function docs to match new pagination and error behavior.

Prompt pattern:

Update the existing documentation for this function to reflect the current implementation.

Review checklist:

  • Parameters and defaults are current.
  • Examples match real invocation patterns.
  • Return type and exception docs are correct.

6) Writing discussions or blog posts

Cookbook workflows include:

  • Brainstorming topics from recent PRs/issues.
  • Outlining a post.
  • Drafting prose.
  • Refining tone and adding actionable next steps.

Useful prompt fragments:

  • Mention specific PR/issue links for context.
  • Specify audience (maintainers, contributors, users).
  • Ask for structure (problem, solution, code excerpts, impact, next steps).

Cross-cutting documentation practices

  • Always define audience and output format.
  • Include repository artifacts (PRs/issues/files) in prompts.
  • Verify generated docs against current code before publish.
  • Separate factual statements from interpretation.

Worked example

Scenario

An API function gained pagination and new error responses, but docs are stale.

Prompt 1 (understand code)

Explain the current behavior of this function for maintainers.
Include parameters, defaults, return values, and error cases.

#file:src/api/listUsers.ts

Prompt 2 (sync docs)

Update the existing documentation to match current implementation.
Return markdown with sections:
- Summary
- Parameters
- Response shape
- Error behavior
- Example request/response

Prompt 3 (review for drift)

List any claims in this updated doc that are not provable from the current code.

Validation checklist

  • Parameter names/defaults match source.
  • Error cases are complete and accurate.
  • Examples compile mentally against actual code behavior.

Key takeaways

  • Documentation prompts should always include audience, scope, and format.
  • Legacy code explanation is more effective with language-bridge analogies.
  • Docs must be synchronized with code changes to avoid long-term drift.
  • Issue and blog drafting can be accelerated safely with a strong review pass.


References

Post a Comment

0 Comments