How to use GitHub Copilot for writing API tutorials

Are you a Technical Writer working on developer documentation? Do you need to explain processes that involve code? Do you wish you could understand the code you need to add to the documentation you’re writing or editing? In that case, Gen AI writing tools are the answer to all your worries.

A while back, I was asked to help create API tutorials and videos aimed at Developers to help them use a new AI product. I didn’t know much about AI and had very basic programming notions, but with the help of GitHub Copilot, I was able to pull it off. In this article, I’d like to share with you some of the things that I learned in the process.

Business challenge

At SoftServe, our Technical Communication Office (TCO) attends to vast documentation requirements. As Tech Writers, we not only help create API reference guides, but we also have the challenge of empowering Developers to feel confident and creative with the API endpoints described in the reference guides. API tutorials help solve this challenge. They go beyond reference guides and the typical “Hello World!” example found in a Getting Started section.

Creating API tutorials requires a threefold skill set. You need to have:

• Knowledge of real-world use cases for the API product.
• Understanding of how to use the API or SDK endpoints and make them interact to comply with business requirements.
• Ability to effectively teach others how to put all the pieces together, one step at a time.

The process of creating API tutorials requires team effort. Even though Developers contribute to the process of writing API reference guides, they don’t have much time to write tutorials, nor do they commonly have the specific skills needed to write complete and easy-to-follow documentation. Technical Writers, on the other hand, although experts in tackling the tedious job of composing step-by-step tutorials, often lack the coding skills to make an API tutorial on their own.

Ideally, Developers should provide Technical Writers with steps and code snippets for the tutorial. And even though nothing (so far) can replace an interview with a subject matter expert (SME), the Writer will have to eventually understand what the code does and be able to put it all together.

Solution

Gen AI writing tools can give Technical Writers a boost by helping them understand and write code. In this article, we’ll briefly examine how to use GitHub Copilot to create an API tutorial for developer documentation.

Why use GitHub Copilot? Although most Large Language Models (LLMs) can help you with code-related tasks, GitHub Copilot works seamlessly along with code editors like VS Code. Consequently, Copilot has a holistic view of your code and documentation, helping you understand everything that’s going on and even project possible scenarios.

GitHub Copilot is ideal for those who write technical documentation using the docs-as-code methodology. If you’re using a code editor to write documentation that lives in the same repository as the code and a markup language, like Markdown, Copilot will add suggestions directly to the document you’re working on while writing.

Getting started with GitHub Copilot

GitHub Copilot isn’t free to use. GitHub offers business, enterprise, and individual Copilot plans. If you don’t have access to a business or enterprise plan, you should first consult with your company or client if it’s ok to use a GitHub Copilot Individual plan. The reason is security. GitHub guarantees that no data from GitHub Copilot Business and GitHub Copilot Enterprise plans will be used to train its AI, but does not offer the same for individual plans. This means that the code used in individual plans is exposed to the public.

To use a GitHub Copilot Individual plan, you should consider the following:

• Make sure your company or client is ok with you using it.
• If private data is stored in the code, replace it with some placeholder.
• If the code is stored in a public GitHub repository, relax because there are no privacy concerns.

Interacting with the tool

After getting access to GitHub Copilot and installing it in a compatible code editor, you can interact with Copilot in several ways.

Below are a few screenshots of the interaction between Visual Studio Code and GitHub Copilot while preparing an API tutorial.

For long dialogs, you can open a side panel in your editor to chat directly with Copilot.

And for specific commands or indications, you can open an inline chat box that appears on top of the very text or code you’re editing.

Copilot also gives you suggestions right in the editor window as you write your code or document. And you can also write comments in your code or documentation to fine-tune Copilot suggestions.

The tool works simultaneously with all the opened files in your code editor. So, to help Copilot have more context about the code or documentation you’re writing, open all the related files.

Subject matter experts

As mentioned above, you need a team effort to write API tutorials. You’ll need to understand a real use case task and get an idea of how the endpoints are used in each step of the process. If possible, ask for code snippets of the API requests and responses that you can use in the corresponding steps of the process. Don’t worry if you don’t understand the code. GitHub Copilot will help you not only understand the code so that you can describe it to your readers, but also refactor and beautify the code for you. That means that it can make the code more legible and easier for a human to follow.

Sometimes things get complicated, and there is no subject matter expert to talk to. Don’t worry, GitHub Copilot can help you out. If the API reference guide is pretty much complete and it contains request code snippets and response descriptions, then you have at least half of what you need. The other half is knowing exactly what task you want to carry out so that you can figure out which endpoints to use and how to handle the data in the responses.

Code sample language

And before you continue, you should decide which programming language or languages you want to use in your tutorial. Generally, the programming language in a tutorial is defined by the intended end-user. This decision should be taken by your team.

Don’t worry if you know nothing about the chosen programming language. As long as you have a clear understanding of the logic used to carry out the programming task you want to portray in the tutorial, you have everything under control. Along with helping you understand the code snippets you got from the SME or documentation, GitHub Copilot will also translate them to other programming languages you might want to make available in the tutorial.

Writing process

Once you have the required information from the SMEs or documentation, you can start writing. Create your document in the code editor and start writing the general outline, including the title, subtitles, and the steps to carry out the task.

Remember to write comments with descriptions, instructions, or guidelines for each section of your document. In a code editor, comments are lines or sections of text that the system will normally ignore. But Copilot can read these comments to get a better picture of what you are trying to do.

Next, add your code snippets. Pretty soon, you’ll marvel at how Copilot will start suggesting text to describe the steps and code you’ve added. Also, through the chat panel, you can ask Copilot to explain your code snippets, tell it to clean the code up a bit, or ask pretty much anything related to the document you’re trying to create.

Response handling

Understanding how to deal with API request responses is essential. Sometimes, you just need to retrieve a small amount of data from a response to then use that data for another task or request. If you already have documentation to help you interpret responses, then you can tell Copilot to write code that will handle the exact data that you need to extract from the request’s response.

For example, let’s say a request returns an array of objects in JSON format, and you only need the value of one property within the object. You can ask Copilot to write a piece of code that will go through objects in the array, extracting only the information you need.

You can then use this code in the tutorial to help Developers get a taste of the data they are working with. It’ll also help them easily integrate various endpoints to complete a specific task.

Advanced steps

If you have some notions about programming and can do some basic things with the code editor, then you should definitely try going the extra mile. With the help of Copilot, try implementing the very same tutorial to carry out the task. Copilot will help you along the way. Start off by writing an elaborate prompt in the chat panel to tell Copilot what you want to do. Follow its instructions and ask how to solve problems whenever needed. And trust me, there’ll be a lot of issues with the code you’re trying to write, but don’t worry, you’ll figure it out with Copilot’s help.

The very same process of writing the code to carry out a task using the API or SDK endpoints will help you better understand how everything works. And thus, enabling you to go back to the tutorial and improve it. You’ll know how to describe things better, add more steps when required, and even trim the tutorial a bit by removing interesting but unnecessary details, steps, or code.

Double-checking

At times you’ll get the feeling that Copilot can read your mind or predict the future, but don’t trust it too much. Although Copilot can elaborate sophisticated suggestions, sometimes it can be inaccurate in relation to the context you’re working in. So, always double-check, just in case.

Conclusion

So far, although Gen AI technology can assist in the process of writing technical documentation, it can’t replace Tech Writers. It still lacks the creative experience that Technical Writers use to put content, context, and end-user needs together in a simple and complete tutorial that is linked and structured within an architecture of content.

Don’t be afraid to experiment using GitHub Copilot or other AI tools to help you write API tutorials. You’ll soon see how they empower you to write even better and more advanced API documentation.

And what AI tools do you use to enhance API docs?