Skip to main content

AI use case: Generate documentation with AI

Writing overviews, summaries, user guides, release notes, and feature overviews is one of the most popular ways technical writers use AI tools such as ChatGPT, Claude, and Gemini. However, AI cannot yet scan your mind and instantly generate the desired output. To achieve the results you want, you need to provide clear instructions and structure. This article demonstrates how to do this by walking you through a practical use case of using ChatGPT for technical documentation. You'll learn how to:

  • Create templates for consistent document structure
  • Write effective prompts that guide the AI
  • Prepare and organize supporting materials
  • Test and refine the AI's output

The article includes a real-world example of documenting template configurations, complete with a sample prompt and template. Whether you're documenting software features, API endpoints, or configuration parameters, these techniques will help you maintain consistency across your documentation.

Use case scenario: AI-powered documentation templates​

Your company regularly creates dozens of templates, which are available in Back Office. Your marketing team uses these templates to create visually appealing HTML pages. Depending on the team's marketing strategy they choose and configure these templates in the back office: upload images, add texts and colors, set up rules for dynamically changing text, and so on. Some configurations are straightforward, while others are more sophisticated, have dependencies from other templates, limitations, and edge cases that are not obvious, especially to newcomers.

As a technical writer, to document configuration fields, exceptions, and behavior specifics for each template, you gather all information about a new template, which may include the following:

  • JSON file defining a template's structure in the Back Office and configuration field headings
  • Information from Jira tickets—each template has one or several tickets containing all information needed for writing the document
  • Screenshots of Back Office configurations and how they look when configured and rendered on an HTML page
  • Subject-matter expert interviews covering key points, specifics, and edge cases of the template configuration

In this scenario, your steps would be as follows:

  1. Prepare the first document.
  2. Create a document template for ChatGPT
  3. Upload all necessary files
  4. Test and refine the prompt

These steps are covered in detail in the following sections.

Prepare your first document​

Create the first demo document and get approval from your team. You'll later use it as a basis to create a template for ChatGPT. The document must be complete and cover all aspects:

  • Finalized structure: Think through all the structure details: introduction, prerequisites, notes, screenshots, configuration steps, and reference links.
  • Content completeness: Ensure you've documented all configuration options, edge cases, and dependencies.
  • Visual elements: Include relevant screenshots and diagrams showing how configurations look in both the Back Office and when rendered on the page.

Create an AI documentation template​

To get documents with the desired structure, create a markdown template for the AI to use when generating documents. Preparing a good template is a time-consuming process because you need to think through everything. It's like creating a detailed guide for the AI that covers all steps in detail. The recommended approach is to take your document, go through it line by line, leaving detailed instructions and adding examples and placeholders where you want the AI to replace or add something specific.

Here are general rules to follow to write a good template:

  • Use placeholders: If the document has a static text where only part of it needs to change, use placeholders indicating the dynamic word or phrase, followed by explanation which values should it be replaced with. Use one placeholder for the same word or phrase. For example, the following sentence has a placeholder that indicates that the AI must replace it with a template name: This document describes Back Office configs of the {TEMPLATE_NAME} template. Replace {TEMPLATE_NAME} with a template name from the input data. Example: demo_config,
  • Provide examples of desired output: Upload your document so that the model can put everything together and thus have a more complete understanding of what you want. Example: The attached markdown document describes Back Office configs of the demo_config template.
  • Define structure rules: Specify how headings should be formatted, what sections are required, and how content should be organized. This helps the AI maintain consistency across all generated documents.
  • Include style guide requirements: Add specific formatting rules, such as how to format code snippets, when to use bold or italic text, and how to structure lists. You can either move out the rules into a separate document or add them under the template in the same file. This ensures the AI follows your company's style guide.

Write effective AI prompts​

Once the template is ready, prepare a prompt that gives the AI clear step-by-step instructions. Here are general rules for writing a good prompt:

  • Clarify your goal:: Start by stating the exact outcome you want. If you need a specific document format, highlight that before anything—the output must be a markdown code block
  • Provide relevant context: Explain the use case and why the output matters. Mention or upload any background information references, such as conversations, images, or specific requirements the AI should factor in. Incorporate all relevant details from the attached JSON schema, images, and transcript
  • Upload a template: The most important step is to provide a Markdown template and point the AI to it explicitly. For example, Follow the structure and rules from the uploaded configuration_parameters_template.md markdown sample file
  • Ask for clarifications: Instruct the AI to request more details if needed. This helps ensure no critical information is overlooked. For example, Confirm any clarifications you need before starting

Upload supporting documentation​

Provide the AI with all necessary information so that it has context for filling out the template: a JSON schema, descriptions of Jira tickets, interview transcription, screenshots, a sample document, and so on. Ensure that the data is consistent and up to date.

Test and refine your AI prompts​

Having a good prompt doesn't guarantee the desired result. Testing and refinement are crucial steps in the process. Here's how to approach this:

  • Start with a small test case: Begin with a simple template configuration that has fewer parameters and dependencies. This helps you identify issues in the prompt without getting overwhelmed by complexity. For example, test with a basic template that has only 5-10 configuration fields before moving to more complex ones.

  • Check for common issues:

    • Missing information: If the AI omits important details, add explicit instructions about what must be included. For example: "Make sure to document all edge cases mentioned in the Jira ticket."
    • Incorrect formatting: If the output doesn't follow your style guide, figure out what rules exactly are skipped and add more specific formatting rules to the template.
    • Inconsistent terminology: If the AI uses different terms for the same concept, provide a glossary of approved terms.

  • Iterate based on feedback:

    • After each test, review the output.
    • Note what worked well and what needs improvement.
    • Update the prompt and template accordingly.
    • Test again with the same example to verify improvements.

  • Document your findings:

    • Keep track of what changes improved the results.
    • Create a checklist of common issues to watch for.
    • Share successful prompt patterns with your team.

Remember that refining prompts is an ongoing process. As you work with different types of templates and configurations, you'll discover new ways to improve your prompts and templates.

Example prompt, template and result​

This section demonstrates the practical application of the techniques discussed in preceding sections:

  • A complete prompt that incorporates all the best practices we've covered
  • The template structure used to guide the AI
  • The final output showing how the AI processed the information
  • A comparison between the raw markdown and the rendered result

This example focuses on documenting a template configuration, but the same principles apply to other types of technical documentation.

Prompt example​

Prompt text:

Create a single Markdown file named t-demo-config.md. Incorporate all relevant details from the attached JSON schema, images, and transcript.
Your goal is to document the configuration parameters for the demo_config template following the structure and rules from the uploaded configuration-template.md markdown sample file.
The output must be a markdown code block. Please confirm any clarifications you need before starting.

Attached files:

  • JSON schema, info from Jira tickets
  • Screenshot of a rendered template
  • Screenshot of the template's configuration fields in the Back Office

Template:

Click to view template example
---
title: Template {TEMPLATE_NAME} configuration parameters
description: Learn about configuration parameters of the {TEMPLATE_NAME} template
last_update:
  date: {CURRENT_DATE}<!-- format d/m/yyyy, for example, 4/10/2025-->
---

This document explains the configuration parameters of the `{TEMPLATE_NAME}` template, including detailed descriptions, example values, and visual examples of how the configurations appear on screens.

<details>
<summary>Template {TEMPLATE_NAME} example</summary>

![Template {TEMPLATE_NAME} example](/docs/wellfunnel-studio/templates/working-with-templates/template-{TEMPLATE_NAME}/{TEMPLATE_NAME}-configuration-parameters.md/{TEMPLATE_NAME}.png)
<!--
Replace {TEMPLATE_NAME}:
- Everywhere except file and image paths, use the original template name with underscores—for example, t__product_select_body.
- In file and image paths, use the template name in a dash-separated format. Example: for t__product_select_body, it's template-t-product-select-body.

Example:

<details>
<summary>Template t__demo_template example</summary>

![Template t__demo_template example](/docs/templates/template-t-demo-template/t-demo-template-configuration-parameters.md/t-demo-template.png)

</details>
-->

</details>

{HEADING_LEVEL} {CONFIG_TITLE} {ENITITY_TYPE}

<!--
Replace {CONFIG_TITLE} with the respective title of the configuration section or field taken from the JSON file. The letter case must be inherited from the JSON file's title parameter value and can't be changed to fulfil the style guide rules.

Replace {ENITITY_TYPE} with the type of the configuration. For objects and arrays, use "block". For objects/arrays whose title already contains "block" or for strings and properties, ignore this placeholder.

Replace {HEADING_LEVEL} with the appropriate heading level:
- For the first main object, use H2 headings (##).
- For the following child items, reduce the heading level by 1 step based on the JSON structure.
- If the final document would end up having more than four heading levels (####), then:
  - Make H3 (###) become H2 (##).
  - Make H4 (####) become H3.
  - H2 remain H2.

For properties of arrays and objects, use one level lower than their parent’s heading.

Examples:

For this object, we have "## t__demo_template block" and "### Title text":

{
  "title": "t__demo_template",
  "type": "object",
  "required": [],
  "properties": {
    "$title": {
      "type": "string",
      "title": "Title text"
    },
    ...
  }
}


For this array, we have:
- "## Variations",
- "### Text row",
- "#### Left part text":

{
  ...
  "mainBlock": {
    "type": "array",
    "title": "Variations",
    "items": {
      "type": "object",
      "title": "Text row",
      "properties": {
        "$leftText": {
          "type": "string",
          "title": "Left part text"
        },
        ...
      }
    }
  }
}

-->

--- <!--Add the splitting line for objects and arrays only-->

- **Description:** {DESCRIPTION}
<!--
Replace {DESCRIPTION} with a description generated based on the provided info.

For objects and arrays:
  - Don't use "- **Description:**". Start right away from the description tag.
  - Start with "The **{CONFIG_TITLE}** {ENITITY_TYPE} {VERB}"
    - Examples: lets you configure…, creates…, manages…, etc.
  - Provide a 2–3 sentence summary of what it controls.
  - Example: "The **t__demo_template** block lets you configure a single score row consisting of a title, color, and score logic. This row contributes to a total score calculation and can be used in combination with other rows or templates like `t__user_level_feedback` to display user-specific outcomes."

For strings or properties:
  - Do NOT use {CONFIG_TITLE} directly in the description.
  - Describe what this specific item is responsible for. Start from a verb in the imperative form or past simple.
    - Examples: "Sets", "Lets you...", Used for…", "Defines…", etc.
  - If {CONFIG_TITLE} is connected to another {CONFIG_TITLE}, refer to it in brackets.
  - Example: "Checkbox responsible for the visibility of a divider line under [Total block](#total-block). If selected, the divider line is displayed."
-->
- **Format:** {FORMAT}
<!--
Replace {FORMAT} with one of the following (if applicable). If none fit, mention the custom format in {DESCRIPTION} and REMOVE this "- **Format:**" line.

Possible values:
- Text
- Number
- CDN URL
- HEX color code
- Drop-down list with the following options:
    - **{ENUM_VALUE_1}**: {ENUM_DESCRIPTION_1}
    - **{ENUM_VALUE_2}**: {ENUM_DESCRIPTION_2}
    - ...
    - **{ENUM_VALUE_N}**: {ENUM_DESCRIPTION_N}

If it's "enum": [true, false], remove the "**Format:**" line. Instead, handle it in the **Description** (explain what happens when true or false).

Examples:
- **Format:** Text
- **Format:** Number
- **Format:** HEX color code
- **Format:** Dropdown with the following options:
  - **caption-small**: 10&nbsp;px
  - **small-text**: 14&nbsp;px
  - **caption**: 12&nbsp;px
-->

- **ICU support:** ✅<!--Include this line only when "**Format:** Text." Otherwise, remove it.-->
- **Translation support:** ✅<!--Include only when "**Format:** Text." Otherwise, remove it.-->
- **Example values**: {EXAMPLE_VALUES}
<!--
Replace {EXAMPLE_VALUES} with example values. Don't embrace example values in quotes. Only include "**Example values**" if one of these formats applies:
- **Format:** Text
- **Format:** HEX color code
- **Format:** CDN URL

- For "HEX color code": Provide values like `#000000`, `#FFFFFF`.
- For "CDN URL": Use a path like:`https://example-cdn.com/assets/{config-title-lowercase-dash-separated}.webp`
  - Example: `https://example-cdn.com/assets/icon-after-text.webp`
- For "Text": Provide a short sentence in backticks. Example: `"Please agree to our terms."`
-->

<details>
<summary>{CONFIG_TITLE} example</summary>

![{CONFIG_TITLE} example](../../../../../static/docs/wellfunnel-studio/templates/working-with-templates/template-{TEMPLATE_NAME}/{TEMPLATE_NAME}-configuration-parameters.md/{CONFIG_TITLE}-example.png)
<!--In the image path, use {CONFIG_TITLE} in a dash-separated format. Example: checkout-title -->

</details>

For instructions about adding files to the CDN server, see [Add files to CDN server](/docs/features/add-files-to-cdn-server.md).
<!--Add this line only if the first format item is a CDN URL. Otherwise, remove it.-->

For information about image compression specifics, see [Image compression through Back Office interface](/docs/back-office/other/image-compression-through-back-office-interface.md).
<!--Add this line only if the first format item is a CDN URL. Otherwise, remove it.-->

## Related documents

- [Configure {TEMPLATE_NAME}](/docs/templates/template-{TEMPLATE_NAME}/configure-{TEMPLATE_NAME}.md)

Response example​

---
title: Template t__demo_template configuration parameters
description: Example documentation showing how a typical template might be documented
last_update:
  date: 4/14/2025
---

This document explains the configuration parameters of the `t__demo_template` template, including descriptions, example values, and visual references to how the configurations might appear.

## t__demo_template block
---

The **t__demo_template** block allows you to define feedback screens and text parameters for displaying a user’s resulting score. It controls the main score label text, title size, text alignment, and additional variations for different score ranges.

### Title text

- **Description:** Sets the title label that appears as the main score indicator.  
- **Format:** Text  
- **ICU support:** ✅  
- **Translation support:** ✅  
- **Example values**: `total score`

### Title size

- **Description:** Determines the heading size for the score variations’ title. It applies to all score variation headings.  
- **Format:** Dropdown list with the following options:
  - **h3**: Large heading, 24px
  - **h4**: Medium heading, 20px
  - **h5**: Small heading, 16px

### Text alignment

- **Description:** Defines how the score variation title and subtitle are aligned.  
- **Format:** Dropdown list with the following options:
  - **left**: Align content to the left
  - **center**: Center the content

### Score variations
---

The **Score Variations** block lets you define several result screens triggered by the user’s final score.

#### Score to trigger

- **Description:** Sets the threshold at which this variation activates.  
- **Format:** Number  
- **Example values**: `10`, `50`

#### Screen title

- **Description:** Defines a heading shown on the result screen for this particular score range.  
- **Format:** Text  
- **ICU support:** ✅  
- **Translation support:** ✅  
- **Example values**: `"Your  level is beginner"`

#### Screen subtitle

- **Description:** A short descriptive subtitle shown under the main title in this variation’s feedback screen.  
- **Format:** Text  
- **ICU support:** ✅  
- **Translation support:** ✅  
- **Example values**: `Results are calculated based on recent activity.`

#### Label icon

- **Description:** An optional icon displayed beside the screen title for this variation.  
- **Format:** CDN URL  
- **Example values**: `https://example-cdn.com/assets/label-icon-example.webp`

#### Score explanation

- **Description:** Displays a short explanation or summary related to the user’s score for this variation.  
- **Format:** Text  
- **ICU support:** ✅  
- **Translation support:** ✅  
- **Example values**: `We'll personalize your training based on your final score.`

## Related documents

- [Configure t__demo_template](/docs/templates/configure-t-demo-template.md)