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 1. 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 2, 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:

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

Accordion component documentation generated by Google Bard.
A prompt for writing accordion documentation and output generated by Bard.
Updated prompt for component documentation includes expert inspiration and formatting output with British English spelling.
Updated prompt for component documentation includes expert inspiration and formatting output with British English spelling.

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 3, an extension that can batch-process any number of records, to generate component documentation.

Airtable base setup for component documentation with AI.
Airtable base with components and variables to form a dynamic prompt. GPT Assistant generates documentation based on the dynamic prompt.

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 4.

Markdown Editor to polish component documentation in Airtable.
Editing the markdown output directly in Airtable.

Results #

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

    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 QualityJakob 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 ↩︎

    Leave a comment

    Your email address will not be published. Required fields are marked *

    This site uses Akismet to reduce spam. Learn how your comment data is processed.