Help Center

Using AI for Design System Documentation

Michelle Chin

Artificial intelligence (AI) is all the rage right now. People are experimenting with it for all kinds of stuff – creating images, creating movies, writing content, and so much more! There’s also a good amount of controversy and a call for responsibility and accountability around using AI.

We definitely believe that AI is a useful tool that will change the world, and you can even use it in your work today. In this guide, we’ll explain what you need to know about using AI for documentation, frameworks you can use, pro tips, and things to avoid. By the end, you’ll feel confident in using AI to assist with writing your design system documentation.

Using AI for Documentation

When we talk about AI, we’re referring to a computer’s ability to perform cognitive tasks that we identify with human thinking. There are several companies and models for AI available. However, OpenAI, an artificial intelligence company, is probably the most renowned since it created several popular AI models including ChatGPT.

Launched in November 2022, “ChatGPT is an AI language model developed by OpenAI. It is based on the GPT-3.5 architecture, which represents “Generative Pre-trained Transformer 3.5.” Having undergone extensive training on a diverse dataset from the internet and other sources, ChatGPT has acquired the ability to comprehend and produce human-like responses to various inquiries and prompts. Its main objective is to aid and furnish valuable information to users. Anyone can feel free to ask ChatGPT anything they wish to know!” (I asked it to provide a concise definition of what it is.)

While there are several AI models and tools, we’ll specifically focus on using ChatGPT for documenting design systems.

AI doesn’t replace you

A big misconception is that AI can replace you. (Maybe as it advances, it might but for the foreseeable future, it won’t.) You’ll find that if you try to have AI replace you, you’re often left with clearly mediocre results. For example, if you ask ChatGPT to, “write the guidelines for my button component,” it’ll quickly provide content, but some of it will be incorrect or inaccurate regarding your specific design system. ChatGPT will also state these inaccuracies with confidence, which are known as “AI hallucinations.” Depending on your level of expertise, you could believe these hallucinations as true since we’re used to clues that humans provide when they’re unsure. When humans are often uncertain, we might preface our statements with, “I’m new to this…” or “I could be wrong, but I think…,” which ChatGPT would never say.

Instead of replacing you, AI is a tool that helps you do your job more efficiently. Think of AI as a bicycle. Before you had a bike, you had to walk to the store, and it would take you 15 minutes. But with a bike, you can get to the store in 5 minutes. The bike helps you get to the store more efficiently, but it didn’t tell you how to get there or do the steering for you. You still controlled how fast to go, when to turn, and the best route to take. Similarly, you’re still in control of what content you provide and want from AI.

Instead of replacing you, AI is a tool that helps you do your job more efficiently.

Benefits of using AI for documentation

At a high level, the main benefits of using AI for documentation include:

• Working more efficiently – design system maintainers are often busy, and using AI to assist with documentation can make this task much easier and quicker!
• Expanding your thinking – it’s impossible to know everything, and AI can provide you with a different perspective, other ideas, or more inspiration to help you work better.

The best uses of AI for documentation

Through our own experiments with using AI for documentation, we found two really good ways to leverage it: improving your documentation and writing and brainstorming ideas and finding inspiration for documentation.

Improving your documentation or writing

As design system makers we know all the details of what we want to be documented but writing it a way that people can easily understand often takes time and skill. AI is great at the latter once it has the content, even if it’s chicken scratch notes.

When it comes to writing, here are some things you can use it for:

• Writing short paragraphs based on the content you want to include – so anywhere in your documentation where you have longer content like design principles, getting started guides, overview paragraphs, etc.
• Paraphrasing content – if you’ve written too much or you’re pulling from existing content, it can shorten it.
• Simplifying content – if you’ve written something more technical and want it to be understood by a broader audience
• Transforming content – if you have a list of usage guidelines as notes, you could ask it to create bullet points for them (and even have them grouped into categories)

Brainstorming ideas and finding inspiration

We’re strong proponents of only documenting what’s necessary (i.e., things that exist in your design system today, not random scenarios or “nice to have someday” details). But sometimes, we might miss some practical usage guidelines.

You can use ChatGPT to explore additional aspects to include in your documentation. For example, you ask, “What are some typical usage guidelines for button groups?” You may get results that you didn’t consider before, like “limit the button count.” Before adding that into the guidelines, we recommend double-checking with your design system team (via your governance process) to see if that should be included.

How to use ChatGPT to help with documentation

Step 1. Set up ChatGPT

If you haven’t used ChatGPT before, you’ll need to set up an account. It’s free to create an account. To do so:

1. Visit https://chat.openai.com
2. Select Sign up
3. You can create an account via your email or through an existing Google, Microsoft, or Apple login

Once you’re signed in, you’re ready to go!

Step 2. Use the CIGO framework to write good prompts

ChatGPT is just like texting a friend a question and getting an answer. Your message to ChatGPT is called a “prompt.” The better your prompts are, the more useful ChatGPT’s response will be (and the less iterating you’ll have to do with it.)

At zeroheight, we created the CIGO framework to help you write prompts to get the most out of ChatGPT’s abilities when it comes to design system documentation. CIGO stands for Context, Information, Goal, and Output. When you write your prompt, you’ll include each of these aspects.

Context

Context is the background information ChatGPT will need so it can provide the right level of voice and tone.

Ask yourself: What is this for? Who will be consuming the output?

Example: This is for my design system documentation. The information will be read by developers, designers, and content writers, who have some technical knowledge already.

Information

Information includes the details you need to provide ChatGPT. For documenting a component, it could be the specifics around when, why, and how to use the component.

Ask yourself: What details about the content do I need to provide ChatGPT? What should be included in the output?

Example: The details I want to include are: Primary buttons should be used for the main CTA. There should only be one primary button in a button group; primary buttons should be on the right side. The button labels should be accurate verbs like “Print” or “Purchase,” not vague like “Submit.”

Goal

The goal is the intent of the output ChatGPT produces.

Ask yourself: What is the intent of my request? What do I want the reader to takeaway? What should the reader be able to do after reading things?

Example: The goal is to ensure readers understand how to use primary buttons in the main product.

Output

Output is defining what format you want ChatGPT to provide for its response. This can be a short paragraph, a number of sentences, bullet points, or a do’s and don’ts list.

Ask yourself: What do I want the output to look like? Do I want the language to be concise? Do I want the output to be a maximum number of sentences? Should it be a list of bullet points?

Example: Provide the usage guidelines in the format of a do’s and don’ts bullet point list. Bullet points should be written in a concise, plain language format.

Step 3. Work with ChatGPT

Step 3.1. Send your prompt to ChatGPT

Once you have your prompt, send it to ChatGPT and let the magic happen! Pretty much instantly, ChatGPT will provide a response.

Let’s use the example prompt from the CIGO framework:

This is for my design system documentation. The information will be read by developers, designers, and content writers, who have some technical knowledge already.

The details I want to include are: Primary buttons should be used for the main CTA. There should only be one primary button in a button group; primary buttons should be on the right side. The button labels should be accurate verbs like “Print” or “Purchase,” not vague like “Submit.”

The goal is to ensure readers understand how to use primary buttons in the main product.

Provide the usage guidelines in the format of a do’s and don’ts bullet point list. Bullet points should be written in a concise, plain language format.

And this is what ChatGPT created for us:

Sure! Here’s a concise, plain language format list of do’s and don’ts for using primary buttons in the main product:

Do’s:

• Use primary buttons for the main Call-to-Action (CTA) in your product.
• Place the primary button on the right side of the button group.
• Label the primary button with accurate verbs that clearly describe the action, such as “Print” or “Purchase.”
• Make sure the primary button stands out visually, using appropriate styling and color contrast.
• Use primary buttons sparingly and strategically to maintain their impact and importance.
• Ensure primary buttons have a clear and logical flow within the user interface.

Don’ts:

• Avoid using multiple primary buttons in the same button group. Stick to only one primary button per group.
• Don’t use vague or ambiguous labels for primary buttons. Avoid labels like “Submit” that don’t clearly indicate the action the button performs.
• Refrain from placing the primary button on the left side of the button group.
• Avoid overusing primary buttons throughout the product, as it may diminish their significance and confuse users.
• Don’t neglect the visual design of the primary button. Ensure it stands out appropriately and aligns with your overall product design.

Remember, primary buttons serve as the primary point of user interaction, so their usage should be consistent and intuitive throughout your product.

Overall, it’s not bad, considering this took 2 seconds and would have taken me much longer to write this on my own.

Looking closer, I added green check emojis ✅ to the bullets that were related to the info I wanted the response to include:

Do’s:

• ✅ Use primary buttons for the main Call-to-Action (CTA) in your product.
• ✅ Place the primary button on the right side of the button group.
• ✅ Label the primary button with accurate verbs that clearly describe the action, such as “Print” or “Purchase.”
• Make sure the primary button stands out visually, using appropriate styling and color contrast.
• Use primary buttons sparingly and strategically to maintain their impact and importance.
• Ensure primary buttons have a clear and logical flow within the user interface.

Don’ts:

• ✅ Avoid using multiple primary buttons in the same button group. Stick to only one primary button per group.
• ✅ Don’t use vague or ambiguous labels for primary buttons. Avoid labels like “Submit” that don’t clearly indicate the action the button performs.
• ✅ Refrain from placing the primary button on the left side of the button group.
• Avoid overusing primary buttons throughout the product, as it may diminish their significance and confuse users.
• Don’t neglect the visual design of the primary button. Ensure it stands out appropriately and aligns with your overall product design.

Did you notice that it added some extra bullet items? This is where AI hallucinations can appear, so our work is definitely not done yet.

Step 3.2. Triple-check the result

ChatGPT doesn’t know the full context of your design system, products, or team. So it can often make up stuff based on the content it trained with. It means well, but this information can often be inaccurate. So review the content by asking yourself these questions:

• Did it add everything I asked it to?
• Did it put it in a format that will make sense for my documentation and users?
• Did it add anything else? Do I agree with what it added? If I agree, does keeping it help or confuse my users?
• Is the language accurate?
• Does this match the voice and tone with the rest of the documentation?

For instance, in this example response, I find some of the phrasing questionable.

My guideline: There should only be one primary button in a button group.

ChatGPT’s wording: Avoid using multiple primary buttons in the same button group.

With ChatGPT’s wording, it sounds like it’s not a definite rule that there’s only one primary button in a button group. Instead, “avoid” means “try not to, but you could still possibly get away with it.” But my wording might not be strong either. I could have said, “You can only have one primary button.” And that could yield better results.

ChatGPT also added, “Make sure the primary button stands out visually, using appropriate styling and color contrast.” While I agree with that, the design system team created the button component with that in mind. So while valid, we don’t need to include it as a guideline.

Step 3.3. Edit the response

After you’ve checked the response, feel free to make any corrections and edits for voice and tone. While it seems like an effort, it’s still less work to edit a response than to create one yourself!

If you’re really unhappy with the result, you can refine the response by sending it a follow-up request. For example, “Can you turn this into do/don’t pairs instead of separate bullet lists?” or, “Can you simplify the language even more?”

As you tweak the response or send follow-ups, make note of what you’re changing. This can help you create better prompts in the future. Consider documenting the CIGO framework in zeroheight and include example prompts that yielded good results.

Asynchronous Step. Learn about new ideas and perspectives with ChatGPT

The other cool thing about ChatGPT, especially if you’re new to design systems, is that it can help give you a sense of what content you could include in your documentation.

Using the CIGO framework, you can create prompts to get ideas for usage guidelines for primary buttons. ChatGPT will pull a response together, which might surprise you. You’ll definitely get things that you’re familiar with, but you might find a guideline or two that hadn’t crossed your mind.

Before you add those things to your design system, really evaluate them. Ask yourself:

• Is this true for our design system? Is this something that we haven’t figured out yet and need to? (It might be worth checking with the team.)
• Is this necessary to have in our usage guidelines? ChatGPT will often add some common knowledge “fluff” that designers innately know.
• Is this information true? Every once in a while, ChatGPT will throw in something weird, especially if you’re asking about something more technical, obscure, or recently invented. (Recently counts as anything created after the model stopped training. In ChatGPT3.5’s case, that’s anything after mid-2021.)

As helpful as ChatGPT can seem, you’re still at the helm of making decisions. As a best practice, we recommend only adding what’s absolutely necessary and useful for your viewers to create a source of information that they can trust.

What’s next

If you haven’t used ChatGPT for work yet, this is a great way to start. See how well prompt writing goes and the kinds of responses you get. If things go well, share this article and your techniques with your teammates – I’m sure they wouldn’t mind the efficiency!

But this is just the tip of the AI iceberg. There’s so much more AI can help you do beyond documentation. In the next few months, we’ll explore other ways AI can help you and your design system. Follow us to learn when we write more about this super exciting topic.

If you have ideas or have tried documenting with ChatGPT, let us know! I’d love to hear how it went!