Creating a polished README with GitHub Copilot

Open or Create your README file

Your first step is to open the special README.md file within your project. If it doesn't exist yet, you'll need to create it. This .md part means it's a Markdown file, which is a simple way to format text (like making headings, lists, or bolding words) that GitHub understands.

To do this, look at the Explorer pane on the left side of your VS Code window – it shows all your project files and folders. If you can't see it, press Ctrl + Shift + E (on Windows/Linux) or Cmd + Shift + E (on Mac) to reveal it.

Action: In the Explorer pane, right-click on your project's main folder, then choose "New File". Type README.md exactly as shown and press Enter. What you see: A new input field appears for the filename in the Explorer pane. What happens next: The new README.md file will open as a blank document in the main editor area of VS Code. If it looks different: If you already have a README.md file, simply click on it in the Explorer pane to open it, then clear any existing text if you want to start fresh for this guide.

You'll know it worked when a blank file named README.md appears in the main editor area of VS Code, ready for you to type in.

Start your project description

Now that your README.md file is open, we'll ask Copilot to help write the main description. GitHub Copilot uses what's called "autocomplete," which is like the predictive text on your phone, but much smarter. It uses artificial intelligence (AI) to guess what you want to write next based on your context.

Action: Place your blinking cursor on the very first line of your README.md file, type a brief heading for your project, and then press the Enter key. What you see: After you type the heading, a greyed-out suggestion from Copilot will usually appear right after your cursor. What happens next: Copilot will read your short heading and automatically start suggesting a full paragraph describing your project. If the suggestion looks good, press the Tab key to accept it. If you'd like another option, press Ctrl + Space (on Windows/Linux) or Option + Space (on Mac) to cycle through different suggestions until you find one you like. If it looks different: If Copilot doesn't offer a suggestion immediately, make sure the GitHub Copilot extension is enabled (check the bottom-right corner of VS Code for a small Copilot icon). You can also try typing a few more words of your own before pressing Enter again.

You'll know it worked when Copilot presents a greyed-out text suggestion directly in your editor, and you've accepted a description by pressing Tab.

Generate an installation guide

Most projects need instructions on how to get them set up. Copilot can help generate these common sections too. It often intelligently guesses what programming language your project uses from other files in your repository, and suggests relevant commands.

Action: Move your cursor a few lines down (press Enter a few times to create some space), type ## Installation, press Enter, then type a short prompt like Run the following command: and press Enter. What you see: Your new heading, followed by your cue, and then a greyed-out suggestion for an installation command. What happens next: Copilot will typically auto-complete a shell command (a command you'd type into a computer's terminal) like npm install (for JavaScript projects) or pip install -r requirements.txt (for Python projects). If it looks different: If the suggested command doesn't match your project's language or package manager (the tool that handles software components), simply delete it and type a more specific cue. For example, Install Python dependencies: if it suggested npm install for your Python project.

You'll know it worked when Copilot suggests a command line for installing dependencies, and you've accepted it by pressing Tab.

Add a usage example

Once a project is installed, people need to know how to use it! We can follow a similar pattern to get Copilot to generate a command to start your application.

Action: After your installation section, move your cursor down a few lines, type ## Usage, press Enter, then write a brief cue like Start the app with: and press Enter. What you see: Your new heading and cue, followed by Copilot's suggested command. What happens next: Copilot will propose a command like npm start or python app.py, again, based on what it deduces about your project. Accept the appropriate one by pressing Tab. If it looks different: If the suggested command is slightly off, you can accept it and then manually edit the line to be accurate for your project. You could also add a short, plain English description below the command to clarify what it does, e.g., "This launches the local server on http://localhost:5000".

You'll know it worked when Copilot offers a command to get your project running, and you've accepted it.

Include a project overview

A good README often wraps up with a brief summary of what the project aims to achieve or what key technologies it uses. Let's get Copilot to provide a quick overview.

Action: Move your cursor down a few lines from the usage section, type ## Overview, press Enter, then type a few descriptive words like This project demonstrates... and press Enter. What you see: Your new ## Overview heading, followed by your cue, and then a more detailed summary suggestion from Copilot. What happens next: Copilot will fill in a concise paragraph that summarises the purpose and highlights of your project. If it looks different: If the summary is too general, you can add more specific keywords to your initial cue (e.g., This project demonstrates data fetching and UI components...) to guide Copilot towards a more tailored response.

You'll know it worked when Copilot gives you a short, descriptive paragraph summarising your project, which you can then accept.

Finalise with a license note

It's good practice to specify the license for your project. This tells others how they can use, modify, and distribute your code. The MIT License is a very common and permissive choice for open-source projects.

Action: Below your Overview section, add a new heading by typing ## License, then press Enter. On the next line, type This project is licensed under the MIT License. What you see: The new heading and the license statement appearing in your README.md file. What happens next: You've now completed the essential sections of your README file. Copilot won't typically auto-generate specific license text unless prompted heavily, so it's a good idea to add a common one manually. If it looks different: If you need a different license, you can search online for common license texts (e.g., "Apache 2.0 License text") and copy the relevant statement into this section.

You'll know it worked when the ## License section is visible and complete in your README.md file.