Transforming Docs with GPT

To prepare for an upcoming migration to a content management system (CMS), our team is converting feature-based product guides into topic-based documentation. This shift makes content more accessible by organizing information around user needs rather than product features, helping users find relevant, actionable information and complete tasks efficiently.

To support this initiative, we deployed a series of GPT tools, each with specific roles in breaking down, refining, and verifying documentation based on topic-based principles. These internal GPTs were tailored to address distinct phases in our documentation conversion process, ensuring that each step aligns with topic-based best practices.

This article outlines how each GPT tool contributes to the conversion process, describing their unique functions and how they simplify the shift from feature-based to topic-based documentation.

User Story Architect GPT: Mapping Documentation to User Stories

The first step in breaking down the product guides is creating user stories that capture actions users will take in each feature. Because there were no existing product requirements or user stories, the User Story Architect GPT was instrumental in generating a comprehensive list of user stories from the product guide’s content structure. By mapping each user story to specific headings and subheadings, this tool converts extensive, feature-based information into task-oriented content.

Why It’s Needed: User stories ensure that every part of the product guide reflects user actions, organizing content by user tasks rather than product features—a key to effective topic-based documentation.

Challenges: In some cases, this GPT didn’t cover all sections. Repeated prompts helped close any gaps to ensure a thorough breakdown aligned with user needs. As with all GPTs, reviewing content is essential, as hallucinations may occur.

Document Breakdown Assistant GPT: Creating Concise Concept Topics

After establishing user stories, the Document Breakdown Assistant GPT converts the broader overviews from the original guide into concise concept topics. These concept topics provide focused, easy-to-understand introductions to each main idea. Instead of general overviews, the concept topics are specific and support task completion.

Why It’s Needed: Concept topics are foundational in topic-based documentation, establishing the “why” and “what” of each feature to set context for the user stories and tasks that follow. With the Document Breakdown Assistant, redundant information is minimized, resulting in succinct, targeted concept topics.

Challenges: Ensuring non-redundancy in the generated content sometimes required additional refinement prompts. Requesting further clarification allowed us to achieve more streamlined, user-centered concept topics.

Short Desc Creator GPT: Writing Focused Task Summaries

For task topics, brief, clear descriptions help orient users quickly. The Short Desc Creator GPT was invaluable in creating concise descriptions that capture each task’s purpose without unnecessary details. These descriptions help users immediately understand each task’s objective.

Why It’s Needed: Topic-based documentation prioritizes clarity and brevity, especially in task descriptions. Short descriptions give users a quick sense of each task’s purpose, enabling them to find and complete necessary information more efficiently.

Challenges: At times, the generated descriptions focused too much on “how” rather than “why,” requiring additional prompts to realign with the preference for user-centered clarity.

Google Developer Style Guide Compliance GPT: Ensuring Adherence to Standards

To ensure the new topics adhere to best practices, the Google Developer Style Guide Compliance GPT plays a crucial role. This tool checks each topic for style compliance, aligning with the Google Developer Style Guide to maintain consistent, user-friendly language. However, the tool isn’t infallible, so manual reviews are necessary to catch nuances it might miss.

Why It’s Needed: Compliance with established style guidelines is essential for a consistent and professional tone throughout the documentation. Following the Google Developer Style Guide enhances clarity, consistency, and accessibility.

Challenges: The GPT might occasionally overlook style guide subtleties, so manual revisions and repeated compliance checks are essential. Familiarity with the style guide allows for quick adjustments when necessary.

Why This Approach Was Chosen and Future Considerations

This process became essential due to the impending CMS migration and the need to reorganize feature-based documentation into topic-based content. The GPT tools provided a structured approach for managing this large-scale conversion, though some adjustments and iterative refinements were necessary.

While these GPT tools proved effective, tasks like tagging content, engaging in SME reviews, and adding metadata will still require manual input as the process develops. For now, the tools have accelerated the transition.

Note: The author of this article recommended against a full content breakdown all at once. Instead, the suggested approach was to focus on a small content section to create a minimum viable product (MVP). This would allow for customer feedback on the MVP, helping identify areas for improvement and enabling iterative refinements before undertaking a full-scale conversion.