Transform Your Documentation Workflow with AI: A Hands-On GitHub Copilot Workshop

by Brad Jolicoeur

01/01/2026

Documentation. It's the task every developer knows they should do more of, yet somehow always ends up at the bottom of the priority list. We've all been there—staring at a blank screen, trying to remember the "right" format for an Architectural Decision Record, or struggling to maintain consistency across team documents. What if I told you there's a way to make documentation not just easier, but actually enjoyable?

I'm excited to share a comprehensive workshop that demonstrates how to leverage GitHub Copilot with instruction files to create professional, consistent documentation efficiently. This isn't just another "AI can write docs for you" tutorial—it's a systematic approach to embedding best practices directly into your development workflow.

The Problem with Traditional Documentation

Let's be honest about the challenges:

Inconsistency: Every team member formats documents differently
Lost Knowledge: Standards exist somewhere in a wiki that no one reads
High Friction: Starting a new document from scratch takes mental energy
Onboarding Pain: New team members struggle to learn your documentation conventions
Quality Varies: Without guidance, some documents are detailed while others are sparse

These aren't just annoyances—they're productivity killers that impact code quality, decision-making, and team collaboration.

Enter: Context-Aware AI Documentation

The workshop introduces a game-changing approach: Copilot instruction files. These are markdown documents that provide context-specific guidance to GitHub Copilot when working with certain files or directories. Think of them as "guardrails" that ensure Copilot understands your organizational standards, required sections, and best practices.

Here's what makes this powerful:

🎯 Automatic Consistency

When you create a file in a specific directory (like adr/ for Architectural Decision Records), Copilot automatically applies the relevant instructions. No need to remember formatting rules or search for templates—the structure is built into the creation process.

📚 Institutional Knowledge, Codified

Instead of standards living in someone's head or buried in Confluence, they're encoded in instruction files. These files capture:

Document structure and required sections
Organizational conventions and terminology
Tone and style expectations
Legal and compliance requirements
Best practices and common pitfalls to avoid

⚡ Speed Without Sacrificing Quality

You focus on the substance—the technical decision, the employee's performance, the job requirements—while Copilot handles structure, formatting, and ensuring all required elements are present.

What You'll Learn in the Workshop

The workshop provides three comprehensive exercises that cover common documentation scenarios:

Exercise 1: Creating Architectural Decision Records

Learn how to document technical decisions with proper context, alternatives considered, and consequences. The workshop walks you through creating an ADR for adopting GraphQL over REST, demonstrating how Copilot ensures you include all critical sections while you focus on the technical details.

What makes this different: The instruction file automatically guides the structure, tone, and completeness of your ADR. You'll never again forget to document alternatives considered or skip the consequences section.

Exercise 2: Writing Performance Reviews

This exercise showcases Copilot as a thought partner, not just a content generator. You'll learn a three-document workflow (self-review, manager notes, and official review) and discover how asking Copilot to generate questions before writing helps you provide more comprehensive, actionable feedback.

The secret sauce: Copilot helps you think more deeply about performance by asking questions managers commonly overlook—like specific metrics, impact on the organization, and alignment with company values. This leads to reviews that are both more constructive and more useful for employee development.

Exercise 3: Drafting Inclusive Job Postings

Creating job postings that are clear, compelling, and legally compliant is harder than it looks. This exercise shows how instruction files can automatically ensure inclusive language, proper structure, and accessibility best practices.

Why this matters: Instruction files help you avoid discriminatory language and unnecessarily restrictive requirements while making postings welcoming to diverse candidates—all without having to consult an HR checklist every time.

The Technical Architecture

What makes this workshop practical is its focus on real implementation:

Repository-Level Instructions

A single .github/copilot-instructions.md file provides general guidance for the entire repository—your organization's voice, values, and cross-cutting concerns.

Document-Specific Instructions

Targeted instruction files (.github/instructions/*.instructions.md) provide detailed guidance for specific document types. Each file specifies:

Which file patterns it applies to (using glob patterns)
Required sections and structure
Writing guidelines and examples
Quality criteria and review checklists

The Beautiful Part

Once set up, the system is invisible to users. Create a new file in the right directory, ask Copilot to help, and it automatically follows your standards. No special commands, no manual template selection—just natural, context-aware assistance.

Beyond the Workshop: Practical Applications

While the workshop focuses on ADRs, performance reviews, and job postings, the pattern applies to any standardized document type:

API Documentation: Consistent endpoint documentation with required sections
Incident Reports: Structured post-mortems that capture learnings
Design Proposals: Standard formats for proposing new features
Meeting Notes: Consistent structure for decision-making and action items
Runbooks: Standardized operational procedures

Why This Approach Works

The magic isn't just in the AI—it's in the system. By combining clear instruction files with AI assistance, you get:

Lower Cognitive Load: Writers focus on content, not format
Faster Onboarding: New team members get instant guidance
Quality Assurance: Required elements are never forgotten
Continuous Improvement: Update instructions once, benefit everywhere
Knowledge Transfer: Best practices are preserved and propagated

Getting Started

The complete workshop is freely available on GitHub and takes approximately 90 minutes to complete. You'll need:

GitHub Copilot enabled in VS Code
Basic familiarity with markdown
A willingness to rethink how documentation works

The workshop is hands-on and practical—you'll create real documents and immediately see the benefits. Each exercise includes:

Step-by-step instructions
Sample prompts to use with Copilot
Success criteria to verify your results
Key takeaways highlighting important concepts

Best Practices You'll Discover

The workshop doesn't just teach mechanics—it shares battle-tested techniques:

Prompt Engineering for Documentation

Learn how to write effective prompts that generate specific, useful content rather than generic fluff. The workshop shows the difference between "Create an ADR about databases" and prompts that produce genuinely useful documents.

Discover how to start with basic generation and progressively refine sections, request different perspectives, and enhance specificity—treating Copilot as a collaborative partner rather than a one-shot generator.

Quality Assurance

Understand that Copilot accelerates creation but doesn't replace human judgment. The workshop teaches how to review generated content, verify accuracy, and ensure appropriateness.

Advanced Techniques

Explore chaining requests for complex documents, using Copilot for review and editing, ensuring cross-document consistency, and updating instruction files as needs evolve.

Real-World Impact

Organizations implementing this approach report:

60-80% faster document creation while maintaining or improving quality
Dramatically improved consistency across team documentation
Reduced onboarding time for new team members
Better compliance with legal and organizational requirements
More thorough documentation because the friction is removed

The Broader Implications

This workshop represents something bigger than just better documentation—it's a glimpse into how AI-assisted development will evolve. The pattern of encoding organizational knowledge in instruction files and letting AI apply it contextually scales to:

Code generation following your team's patterns
Test creation matching your testing conventions
API design conforming to your standards
Security reviews checking your requirements

We're moving from "AI writes code" to "AI understands and applies our organizational context." That's transformative.

Your Next Step

Documentation doesn't have to be a chore. With the right tools and approach, it can be fast, consistent, and even enjoyable. The GitHub Copilot Documentation Workshop gives you everything you need to transform how your team creates and maintains documentation.

Take the workshop: Visit the documentation-demo repository and follow the comprehensive workshop guide.

Start small: Begin with one document type that's causing your team pain. Create instruction files, try the pattern, and refine based on results.

Share with your team: Once you see the benefits, propagate the approach. The real power comes when everyone on the team works with the same context-aware assistance.

Conclusion

GitHub Copilot instruction files offer a systematic approach to documentation that addresses the core challenges teams face: inconsistency, lost knowledge, high friction, and variable quality. By codifying organizational standards directly into your development workflow, you create a self-reinforcing system that improves documentation quality while reducing time investment.

The 90-minute workshop provides hands-on experience with three practical scenarios that demonstrate the pattern's versatility. You'll learn techniques that extend beyond documentation to any standardized content your team produces.

When this approach works best:

Teams with established documentation standards needing better enforcement
Organizations onboarding new members frequently
Projects requiring consistent compliance or legal language
Teams experiencing documentation quality issues despite having guidelines

Consider the tradeoffs:

Initial setup requires thoughtful instruction file creation
Effectiveness depends on maintaining up-to-date instruction files
Still requires human review for accuracy and appropriateness
Most valuable for document types created repeatedly

The pattern represents a shift from "AI writes content" to "AI applies organizational context." Start with one document type causing your team friction, create targeted instruction files, and iterate based on results. The time invested in setup pays dividends through faster creation, better consistency, and reduced cognitive load.

Ready to get started? The documentation-demo repository and workshop guide provide everything you need to transform your documentation workflow.

Resources

Workshop Repository: github.com/bradjolicoeur/documentation-demo
Complete Workshop Guide: workshop.md
GitHub Copilot Documentation: docs.github.com/en/copilot
Copilot Chat in VS Code: code.visualstudio.com/docs/copilot/copilot-chat