Faster and better component documentation with AI

Component documentation can be a tedious task. I’m using generative Artificial Intelligence (AI) to document design system components. I use AI to batch write component documentation drafts because I want to be faster at producing them and with higher quality ¹. Writing this type of template documentation is my favourite use case for Generative Pre-training Transformers (GPTs).

A dynamic prompt for component documentation #

Thank you to a teammate who shared their prompt for writing component documentation. I mixed this with the CREATE framework I learned from Dave Birss’ course ², to structure a dynamic prompt for generating component documentation.

CREATE framework to prompt GPT

• Character. Tell it what role to play. It could be an expert, a celebrity, an artist, or a school student.
• Request specifically with context and useful information.
• Examples and inspiration sources. For example, “Draw inspiration from experts like Brad Frost, Dan Mall, Nathan Curtis, Heydon Pickering, Jina Anne, Yesenia Perez-Cruz and Alla Kholmatova.”
• Adjustments and refinements to help shape the response. For example, “Include an explanation of its anatomy, guidelines for accessibility, best practices, a guide on how to use it, and situations when not to use it.
• Type of output. Tell it how to format your output. Paragraphs, bullet points, tables, poems, scripts, etc. Set the length of response or target reading level, for example, “Write up to 500 words, with everything spelled in British English e.g. colour not color, utilise not utilize, and a reading level of 9th grade or less.”
• Extras. For example, “Ask me questions before you answer; Explain your thinking; Act unlike a typical AI.”

My latest prompt for generating component documentation:

You are a talented designer with 10 years of experience writing effective documentation. Write me the documentation for a {{Component}} in the design system, intended for a {{Platform}}. The target audience for this documentation is {{Target audience}}. Draw inspiration from {{Inspiration}}. All components should comply with level AA of WCAG 2.2. Here are the guidelines and main points to mention: The document provides an overview of the component, including an explanation of its anatomy, a guide on how to use it, and situations when not to use it. The document also delves into the differences between the component and other common elements such as {{Alternatives}} if any. In addition to the descriptive information, the document includes guidelines for accessibility and best practices for using a {{Component}}. Use subheads to break up the text. Write everything spelled in British English e.g. colour not color, utilise not utilize.

Substitute your variables in each {{placeholder}} to complete your prompt. Then paste the prompt into your choice of GPT.

It takes AI a few seconds to generate the output. Much time was saved in drafting. Spend some time editing the draft documentation to give it the necessary polish.

You can repeat this process for each component one by one. However, you can save more time by generating documentation in a batch process.

Batch component documentation drafting is even faster! #

I have an Airtable base with component names, platforms, target audiences, inspiration, and other contextual information. Then, I use a formula to concatenate static prompt elements, the component name, and any variables to form a dynamic prompt. Finally, I use GPT Assistant ³, an extension that can batch-process any number of records, to generate component documentation.

The output from GPT Assistant is in the versatile markdown format. Polishing the draft documentation can be done directly in Airtable with the Markdown Editor extension ⁴.

Results #

The following pages are a direct copy-paste of the markdown produced by the GPT Assistant. They have not been edited further.

• Accordion Documentation
• Tabbed Interface Documentation
• Tooltip Documentation

Conclusion #

With a well-crafted prompt and a batch process tool, generative AI can quickly produce draft component documentation in bulk. With so much effort saved on drafting, spending time to polish the draft should raise the quality of the documentation above what it would be without AI.

Footnotes #

1. ChatGPT Lifts Business Professionals’ Productivity and Improves Work Quality – Jakob Nielsen, April 2, 2023 ↩︎
2. How to research and write using generative AI tools – LinkedIn Learning course by Dave Birss ↩︎
3. GPT Assistant – Airtable extension ↩︎
4. Markdown Editor – Airtable extension ↩︎