.png){kind=small}
Project 5 — Document an Existing Repo
Generate README, CONTRIBUTING, inline comments.
What You Will Learn
- Generate a README.md with Copilot.
- Add CONTRIBUTING.md.
- Add inline docstrings.
- Create an ARCHITECTURE.md.
- Prepare a docs PR.
Why This Matters
Most repos have inadequate docs because writing docs is tedious. Copilot can draft them in minutes. A documented repo is easier to onboard to, easier to maintain, and easier to promote.
Concept Explained
Use Copilot to generate README.md, CONTRIBUTING.md, ARCHITECTURE.md, and inline docstrings for a repo with sparse documentation.
How It Works
Use @workspace to give Copilot repo-wide context. Ask for a README summarizing what the repo does. Generate CONTRIBUTING from your project's conventions. Add docstrings with /doc.
Step-by-Step Tutorial
1. Generate README
@workspace 'generate a README.md for this repo. Include: what it does, install, usage, examples, license.'2. Generate CONTRIBUTING
'generate CONTRIBUTING.md based on this repo's conventions (branch naming, commit style, PR template).'3. Generate ARCHITECTURE
'generate ARCHITECTURE.md explaining the repo's structure and data flow.'4. Add docstrings
Run /doc on undocumented functions.5. Prepare PR
Commit docs. Open a PR. Use Copilot for the PR description.Real-World Example
A team inherited a 6-month-old internal tool with zero docs. They used Copilot to generate README, CONTRIBUTING, ARCHITECTURE, and 50 docstrings in 2 hours. Onboarding time for the next hire dropped from 3 days to 4 hours.
Example Prompts / Commands / Code
@workspace Generate a README.md for this repo.
Include sections:
- Title and one-line description
- Install (npm install, env vars needed)
- Usage (3 example commands)
- API reference (link to docs/)
- Contributing (link to CONTRIBUTING.md)
- License
Tone: professional but approachable. Use code blocks for commands.
@workspace Generate an ARCHITECTURE.md.
Explain:
1. The main modules and their responsibilities
2. How data flows through the system
3. Key design decisions
4. Where to add new features
Include an ASCII or Mermaid diagram showing module relationships.
Common Mistakes
- Accepting README without verifying install instructions work.
- Not running /doc on functions — only top-level docs.
- Forgetting to commit and PR the docs.
- Not linking to LICENSE file.
Best Practices
- Use @workspace for repo-wide context.
- Verify install instructions actually work.
- Add docstrings with /doc, not just top-level docs.
- Open a PR — don't leave docs uncommitted.
- Link to LICENSE, CONTRIBUTING, ARCHITECTURE from README.
Troubleshooting
| Problem | How to Fix |
|---|---|
| README is generic | Be specific: 'this is an internal tool for X, used by team Y'. |
| Architecture diagram is wrong | Use @workspace and attach key files explicitly. |
Practical Exercise
Your Turn
This IS the exercise. Pick a repo with sparse docs. Generate README, CONTRIBUTING, ARCHITECTURE. Add 5 docstrings. Open a docs PR.
Professional Challenge
After docs are merged, set up a GitHub Action that runs Copilot on every PR to suggest doc updates for changed code. (Covered in IN-48.)
Key Takeaways
- Copilot drafts docs in minutes from repo context.
- Use @workspace for repo-wide docs.
- Always verify install instructions work.
- Add inline docstrings with /doc.
- Open a docs PR — don't leave uncommitted.
Frequently Asked Questions
Can Copilot generate API reference docs?
What about user guides?
Further Reading
Official References
SEO Metadata
SEO title: Project 5 — Document an Existing Repo
Meta description: Generate README, CONTRIBUTING, inline comments.
Primary keyword: project 5
Secondary keywords: project 5 — document an existing repo
Search intent: Informational
URL slug: /project-document-existing-repo-copilot
Categories: AI Tools, GitHub Copilot
Tags: GitHub Copilot, Beginner, Project, Documentation, README, IMCSEIAN, Tutorial, IMCSEIAN
Featured image concept: IMCSEIAN lesson card for Project 5 — Document an Existing Repo
Comments
Comments
Post a Comment