An AI’s answer is only as up-to-date as the documentation it uses

At the beginning of the year, a merchant seeking assistance with in-person payments approached our AI support chatbot for advice on quickly accepting a payment using their card reader. After consulting our documentation, the AI confidently suggested tapping on the “Simple Payment” option.

However, the merchant could not locate the “Simple Payment” button because it had been renamed to “Add Custom Amount” several months earlier, but the documentation had not been updated to reflect this change. Consequently, the merchant struggled to find the feature described by the AI and eventually gave up.

This incident left a lasting impression on me because the AI performed its task correctly by referencing the documentation available. The issue stemmed from the fact that the documentation still referred to a product that had undergone changes.

The key takeaway here is that when seeking guidance from an AI regarding WooCommerce tasks such as adjusting settings, locating features, or resolving errors, the responses are based on the documentation rather than real-time product knowledge. As the product evolves with each update, discrepancies between the documentation and the actual product can result in confidently delivered yet inaccurate answers.

To address this gap, we developed a WordPress plugin internally at Automattic, which functions as a vigilant documentation updater.

This plugin monitors WooCommerce releases and incoming requests for documentation updates. Whenever a change occurs, such as a button being renamed, a setting being relocated, or a new feature being introduced, an AI model generates an update draft. Before publication, the draft must meet specific criteria:

1. We assess the draft’s quality on a scale of 1 to 5 using our rubric, considering factors like accuracy, voice and tone, structure, grammar and style, findability, and visuals.
2. The draft must also pass automated checks for safety. Any draft that deletes more than approximately 30% of a page, disrupts the page’s formatting, leaves placeholders, or adds new image links is flagged for human review.
3. A member of our team reviews the draft in a preview format and approves it before it is published on woocommerce.com.

One notable aspect of our rubric is the emphasis on findability: the initial paragraph of every document should serve as a standalone answer that an AI can directly quote. This shift reflects our focus on creating source material for AI responses about WooCommerce, rather than merely creating documentation for human readers.

In addition to evaluating new drafts, we also assess the live documentation using the same rubric.

By the end of June, 39 out of the 117 WooCommerce documents we reviewed fell below our quality standards. This necessitated the development of our system. Given that WooCommerce undergoes frequent updates, even the most adept team of writers cannot review every page after each release. However, our plugin can perform this task efficiently by continuously monitoring pages and flagging those that require attention.

A component of the system automatically applies our terminology list to maintain consistency in product names, ensuring the use of “WooCommerce” instead of “woocommerce.” This process involves direct find-and-replace actions.

On occasion, entries in the list were formulated as writing guidelines rather than straightforward word substitutions. Due to this nuance, the system inadvertently included the advice in published documents, resulting in instances where readers were instructed to click on “(descriptive link text describing the destination)” instead of an actual link.

Upon discovering this issue during related work, we conducted an audit of all 258 WooCommerce documents, identified 9 affected documents, rectified each one, eliminated problematic entries, and implemented safeguards to prevent such errors in the future.

I share this example to underscore a common lesson from a different perspective. Automation strictly adheres to predefined rules, acting promptly and impartially. This dual nature makes automation both beneficial and potentially risky. Our system is designed with this duality in mind: rigorous checks that err on the side of caution, human oversight for critical tasks, and audits to validate automated processes.

Implications for Troubleshooting

When seeking guidance from an AI assistant regarding WooCommerce matters, it is essential to consider that the quality of the response is predetermined by the accuracy of the documentation. If the documentation does not align with the current state of the product you are using, discrepancies may arise.

Our responsibility is to ensure the accuracy of the documentation, and the system described above is instrumental in achieving this goal. While your role in this process may be smaller, it remains crucial:

• If the instructions provided by the AI do not match what you observe on your screen, it is possible that the documentation is outdated. Before assuming an error on your part, verify the information in the documentation being referenced.
• If you encounter any discrepancies, please inform us. When interacting with our AI assistant, use the thumbs-down rating or click on ‘Contact Support’ to report inaccuracies. If you come across outdated documentation, provide feedback to our team via the ‘Was this guide helpful?’ feature at the bottom of the page.

In the case of the merchant using the card reader, neither party was at fault. The onus was on us, prompting the development of a system that facilitates swift corrections and proactively addresses changes before they become noticeable.