Drupal AI UX Project Governance: Meta Issue
>>> [!note] Migrated issue
<!-- Drupal.org comment -->
<!-- Migrated from issue #3558401. -->
Reported by: [afoster](https://www.drupal.org/user/594458)
>>>
<p>[Tracker]<br>
<strong>Update Summary: </strong>Consensus established on: UX Task categories, UX Writing principles. Todo: Defining UX reporting + Ops<br>
<strong>Short Description: </strong>Meta issue defining UX governance, reporting protocols, naming conventions, and prioritization for AI ecosystem<br>
<strong>Check-in Date: </strong>05/26/2025<br>
<em>Metadata is used by the <a href="https://www.drupalstarforge.ai/" title="AI Tracker">AI Tracker.</a> Docs and additional fields <a href="https://www.drupalstarforge.ai/ai-dashboard/docs" title="AI Issue Tracker Documentation">here</a>.</em><br>
[/Tracker]</p>
<h2>TLDR</h2>
<p>This meta issue establishes governance systems for managing UX work across the Drupal AI ecosystem. It defines four types of UX issues (Planned Product, Innovation, Audit/Testing, and Contributor-requested reviews), sets standard reporting protocols (module version, URL, screenshots, description), and outlines naming convention principles prioritizing accuracy → site-builder friendly → developer friendly.</p>
<h2>Goal</h2>
<p>We need to establish systems and processes to collect reported UX issues, decide what to prioritize, and assign tasks to UX/Dev teams.</p>
<p>When the Innovation and Product teams are established as part of the AI Initiative, it's clear that UX work will need to span both streams, so we need to start thinking about how to organize this effectively.</p>
<p>After several meetings in #AI-UX with the 1X UX/UI team (Christoph, Angela, Bruno, Yannik) and others with Emma and Jamie, we've identified the need to create a systematic process for managing UX challenges in the AI ecosystem. </p>
<h2>Four Types of UX Issues We Support</h2>
<h3>1. Planned Product UX Improvements</h3>
<p>Ideally, based on improving specific user journeys. These are systematically addressed and reviewed in #AI-UX Meetings.</p>
<p><strong>Examples:</strong></p>
<ul>
<li>Work on issue: <a href="https://www.drupal.org/project/ai_initiative/issues/3554163">https://www.drupal.org/project/ai_initiative/issues/3554163</a> / <a href="https://www.drupal.org/project/ai_dashboard">AI Configuration Dashboard</a></li>
<li>Future planned journeys: <a href="https://www.drupal.org/project/ai_initiative/issues/3550408">https://www.drupal.org/project/ai_initiative/issues/3550408</a></li>
</ul>
<h3>2. Innovation UX Issues</h3>
<p>Generally called out in Slack or on AI/AI-Contrib issues. These are more brainstorming or quick feedback-oriented. They may or may not have issues in Drupal.org.</p>
<p><strong>Examples:</strong></p>
<ul>
<li>Michael Lander cited in Slack: "Install the MCP module and try configuring the plugins for available tools. Right now you have to click the tool in a left tab and then scroll to the top to enable/disable."</li>
<li>"Context summary on the AI Context pools page is not very helpful" - <a href="https://www.drupal.org/project/ai_context/issues/3556875">https://www.drupal.org/project/ai_context/issues/3556875</a></li>
</ul>
<h3>3. Audit/User Testing Reported Issues</h3>
<p>Issues the UX team identifies through systematic review or user testing.</p>
<p><strong>Examples:</strong></p>
<ul>
<li>Emma & Aidan are systematically auditing and creating a "Messy UI" list</li>
<li>Dries's notes included UX/Label comments in the broader feedback</li>
</ul>
<h3>4. AI module contributors request a UX review of something</h3>
<p>Triggered when someone uses specific tags in the issue queue for UX reviews. There will be a tag added to issues to request this, similar to how we will set up a process for QA reviews.</p>
<ul>
<li>We need to set up accountabilities to review the list and delegate the review tasks</li>
</ul>
<h2>Standard Protocol for Reporting UX Issues</h2>
<p>For UX feedback in Slack or on issues, it's challenging to understand the full context of reported problems (especially for work in the Innovation stream, as the module might not be easily installable).</p>
<h3>Required Information for All UX Issue Reports</h3>
<p>When reporting UX issues, please provide:</p>
<ol>
<li><strong>Module Version</strong>: Specific version and sub-modules installed (or git commit)</li>
<li><strong>URL Path</strong>: Exact location where issue occurs</li>
<li><strong>Screenshots</strong>: Visual documentation of the issue</li>
<li><strong>Description</strong>: Clear explanation of the problem and expected behavior</li>
<li><strong>Video</strong> (optional): For complex interaction issues</li>
</ol>
<h2>Standardizing Terminology and Naming Conventions</h2>
<p>There's significant variation in terminology used across the AI ecosystem. We have strong evidence this is confusing (user testing, Dries' comments, anecdotal evidence from onboarding team members).</p>
<h3>Naming Convention Principles</h3>
<p>Within reasonable limits, we should rename labels, features, and help text in the ecosystem to improve UX.</p>
<p><strong>Priority Order:</strong></p>
<ol>
<li><strong>Accuracy</strong> - Information must be technically correct</li>
<li><strong>Site-builder friendly</strong> - Understandable to non-developers</li>
<li><strong>Developer friendly</strong> - Include technical details where appropriate</li>
</ol>
<p>This hierarchy may create conflicts (e.g., explaining "vector embedding provider" to site builders in one line). When conflicts arise:</p>
<p><strong>Implementation Guidelines:</strong></p>
<ul>
<li>Use short, clear labels with industry-standard AI terminology</li>
<li>Place site-builder friendly titles prominently</li>
<li>Include technical details in descriptions</li>
<li>Express "what you get" from AI features in descriptions</li>
<li>Consider tooltips for additional context without UI clutter</li>
</ul>
<h2>The "Messy UI" List: Systematic UX Audit</h2>
<p>Emma and Aidan are working to audit and log UX problems. Given the extensive list of potential improvements, we're creating an audited list in a <a href="https://www.figma.com/design/hwvjCQ1xbT997aLG2WoMqU/UX-Improvement-Audit?node-id=2-5&t=AHQolwmm6lstRCEH-11">Figma Board</a>.</p>
<h3>Audit Focus Areas</h3>
<p>We're documenting two main challenges:</p>
<ol>
<li><strong>Confusing labels/terms</strong> - Terminology that doesn't match user expectations</li>
<li><strong>Confusing UI patterns</strong> - Interface elements that harm the user experience</li>
</ol>
<h3>How We Use the Board vs Issue Queue</h3>
<ul>
<li><strong>Working Space</strong>: The board serves as a working space before specific issues are added to the issue queue (the issue queue is too granular and makes it hard to connect related UX issues)</li>
<li><strong>Triage Process</strong>: Identified UX issues are added to the board for collective review and prioritization</li>
<li><strong>Issue Creation</strong>: Once we're working on a specific solution, the UX issue will be created as a formal issue in the queue</li>
</ul>
<h3>Process Flow</h3>
<ol>
<li><strong>Collection</strong>: Issues reported through various channels</li>
<li><strong>Documentation</strong>: Added to Figma board with context</li>
<li><strong>Triage</strong>: Team review and prioritization</li>
<li><strong>Assignment</strong>: Move to issue queue with clear ownership</li>
<li><strong>Implementation</strong>: Design and development work begins</li>
</ol>
<h2>Decision Framework for Prioritization</h2>
<p>We're prioritizing UX issues that support complete end-to-end task flows and user journeys. The alternative is fixing elements of UX all over the place and we don't want "many half-built bridges"</p>
<h3>Short-term Focus</h3>
<p><strong>Primary Goal:</strong> Enable site builders to successfully set up and use the Canvas AI page builder (as demonstrated in the DrupalCon Vienna Keynote).</p>
<h4>Critical User Journey Dependencies</h4>
<p>This journey requires a seamless flow through multiple setup steps:</p>
<pre><pre>1. Drupal CMS Installation (Out of scope for AI UX team)<br> └─ Via accessible provider (e.g., DrupalForge)<br> <br>2. AI Module Installation<br> └─ Core AI functionality setup<br> <br>3. AI Canvas Content Recipe (to be created)<br> └─ Required components:<br> • AI Core module<br> • AI Canvas module<br> • Context Control Center<br> • Additional supporting modules<br> <br>4. First Successful AI-Generated Page<br> └─ User validation of working system</pre></pre><h4>Prioritization Criteria</h4>
<p>Issues directly supporting this journey receive priority if they:</p>
<ul>
<li><strong>Block the critical path</strong> - Prevent users from completing the setup</li>
<li><strong>Cause abandonment</strong> - Confuse users enough to give up</li>
<li><strong>Create security concerns</strong> - Expose configuration risks</li>
<li><strong>Affect first impressions</strong> - Impact initial user experience</li>
</ul>
<h3>Long-term Framework (Future Releases)</h3>
<p>Once Innovation and Product teams are fully established, they will provide strategic guidance on priorities.</p>
<h2>Next Steps</h2>
<p>
[ ] Post comments, questions, concerns, and objections here or in #ai-ux on Slack<br><br>
[ ] Finalize AI-UX reporting protocol with team feedback<br><br>
[ ] Discuss Naming Conventions, define the "boundaries" of what can be renamed. (Module names? Labels?)<br><br>
[ ] Emma / Aidan: Will start creating specific issues as we work on them as sub-issues here.</p>
issue