Many people think that Copilot Workspace and Github Copilot are only meant for coding. But that’s not true! I found out that you can use Copilot Workspace for documenting your project too. Here are a few ideas to help you get started documenting your project.
Writing a README file with Copilot Workspace
First, I tried to write a README file for my project. If you dislike documenting stuff and always have a lame README file, this is for you.
In your Github repository page, click on the green “Code” button and select the “Copilot” tab. Enter the following task:
Create a README file describing the purpose of the project. Include instructions to get started as a user and instructions how to get started as a developer. Next, click on the “Start task” button to start setting up a plan for the documentation.
The next screen shows you the plan for the task. It should list what’s currently missing, and what will be there after the plan is completed. Click “Generate plan” to set up the plan.
Finally, Click the “Implement files” button to generate the README file.
Notice that the README file won’t be perfect the first time. That’s to be expected, because part of the job is to write a creative introduction and AI isn’t creative at all.
However, you should have a nice set of getting started instructions for users and developers. This is the one thing that I really dislike doing by hand. The creative bit is something that I want to do myself.
Writing README files is nice, but there are more things you can do.
Setting up architecture documentation
Documenting the system architecture of your project is something that you’d normally do by hand because you are designing something new. Coding can be done by AI, but I strongly believe that design is something that I’m much better at.
However, that doesn’t mean AI can’t help me. I hate setting up an outline for my architecture docs because I always use the same template, Arc42. So let’s ask AI to make the outline for my architecture docs.
Go back to the repository page of your project, click on “Code” button, and switch to the “Copilot” tab. Then enter the following prompt:
Create an outline for the architecture documentation for the project. Follow the arc42 template. The template can be found here: https://docs.arc42.org/home/
When you start the task, you’ll be taken to the copilot workspace layout and you’ll have the option to generate a plan, and implement the changes
As you can see from the image, Copilot Workspace derived the outline from the documentation and was able to produce something pretty decent. It proposes to put the architecture docs in the docs folder as well. Sadly, it generates a single file and that’s not how I work.
However, you can ask Copilot Workspace to place each section into a separate file and it will do it for you. When you ask Copilot Workspace to split the sections into separate files, you’ll find that it adds more detail to each section. I found that the details were off in a lot of places, but it was worth keeping because I got some inspiration about the stuff that I needed to cover in my docs.
It’s worth iterating on your docs because Copilot Workspace is a very powerful tool that can do a lot more than you first expect. It took me a lot less time to set up the basics for my architecture documentation thanks to the iteration capabilities of Copilot Workspace.
Since we’re talking about architecture documentation, let’s try to write an architecture decision record to document a decision we made.
Documenting architecture decision records
One of the decisions we have made here is to use Arc42. Let’s document a decision record for it using a well-known template.
I used the following prompt to record the decision:
Document a new architecture decision record recording the decision to use Arc42. Follow this template: https://adr.github.io/madr/examples.html#short-version
The result is pretty good. Maybe we should iterate on the idea and include other options than no template and our own template, but for me this is good enough for now. And look, the architect accepted the decision already, so who cares?!
I can’t stress this enough, be careful what you do here. Architecture decisions are design choices that can only be made by humans. You can of course write a rough version of your decision and then use Copilot Workspace to turn the rough description into a nice decision record.
Summary
Writing documentation is a bit of an unexpected use case for Copilot Workspace for most people, I think. But if you’re not interested in writing documentation the whole day than this is a great way to automate even more boring work.
Have you found interesting use cases for Copilot Workspace? Let me know in the comments!