Writing for machine-assisted experiences

This guidance helps teams think through how and when to signal content assisted by machine learning in the user interface, in ways aligned with Wikimedia’s values.

The focus is on interface content: the words or visuals we use to note and describe machine-assisted outputs.

Content principles

Center the human, not the technology

People come to Wikimedia products to complete a task. Keep the focus on what the person is doing, deciding, or reviewing.

Do

• Focus on the benefit or outcome, not the technology.
• Use active voice for people: add, write, edit, review.
• Use passive voice for AI/ML, like generated by.
• Provide levers for users to provide feedback about the experience (including the output data itself and where/how it’s presented).

Don't

• Frame the system as a partner, coach, or teammate.
• Write copy that makes the machine sound like the primary actor.
• Overemphasize the technology when it is not useful to the user.

Give just enough information

Explain only what people need in order to decide or act.

Do

• Prioritize the information that helps the user complete the task.
• Keep copy short and easy to scan.

• Put technical detail behind a descriptive Learn more link when needed. Link to model cards or other resources as needed.

• Write with the audience in mind: readers, editors, and admins may need different levels of explanation.

Don't

• Add explanation that does not help the immediate task.
• Present too many actions at once.
• Use a third action in a dialog when a link would be more appropriate.

Be transparent

Machine-assisted features should be explained in plain language, without ‘hype’.

• Be specific about what the system does. Consider the data, model, and application separately and decide what the user needs to know about each layer of the system.
• Where appropriate, display any metadata that can help the user contextualize the model’s output (eg. confidence score per prediction). Explain what may be wrong, missing, or misleading when that information helps the user judge the output.
• Use familiar words for the task or topic.
• Explain important limits, especially in admin-facing descriptions and generated outputs.
• Show an information trail when possible for generated outputs, such as sources, keywords, or inputs.

Don't

• Use vague claims about intelligence or capability.
• Rely on jargon when plain language will do.
• Rely on terms that obfuscate how the technology works. Avoid using “AI” or “machine learning” when more specific terms like “small language model” or “classifier model” would be appropriate.
• Hide uncertainty when it affects trust or decision-making.

Choose a level of disclosure

Not every machine-assisted feature needs the same amount of explanation. Choose a level of disclosure based on what people see, what decisions depend on the output, and how much harm could result if the system is wrong.

Risk does not come from the model alone. It can emerge from the data used, the model’s behavior, or the way the output is presented in the interface. Use these factors together to decide how much disclosure is needed.

	Data	Model/Technology	Application/Interface
What this refers to	The information a system uses as input to learn from, analyze, or generate outputs	The computational system or algorithm that transforms data into predictions, patterns, or content	The user-facing system that presents and delivers the model’s outputs
Examples	A sample of 10,000 articles marked with a page template	GPT-5, Two-tower neural ranking models	Chat GPT, Google Search, Instagram
Related concepts	Training data, Evaluation data, Biased data	Generative AI, Discriminative AI, Large language model (LLM), Classifier model	Edit Checks, Structured Tasks, Automoderator

Detailed disclosure

Use detailed disclosure for outputs that are less predictable or interpretable, and applications that are complex or higher risk.

This often applies to generated content, especially when it may be mistaken for human-created content or when errors could meaningfully affect trust.

Include:

• Early disclosure
• A label when appropriate
• A disclaimer
• Clear instructions
• A feedback mechanism
• Supporting detail such as sources, keywords, or reasoning cues when available

Example use cases: long-form generated text, machine-generated summaries, generated translations in high-stakes contexts, automated interventions to prevent abuse, user-personalized content recommendations.

Basic disclosure

Use basic disclosure when outputs are predictable and interpretable, and applications are lower-risk.

Example use case: machine translation, model-provided editing suggestions, non-personalized content recommendations (trending articles, similar articles, etc.).

Components for disclosure

Each component includes any general guidelines and tips by mode, or the type of task performed by the model:

• Flag/Check
• Recommend
• Generate

Titles

For a title, use sentence case. Keep titles action-oriented and easy to scan.

Title the experience based on what the user is trying to do or understand, not on the type of model behind it. Focus on the task, the content, or the outcome.

As an action for a page or card

For Flag or Recommend:

• [verb] [noun]
• Add a link
• Check a fact

For Generate:

• [verb] [noun] or [verb] machine [noun]
• Generate reading list
• Review machine translation

As the name of a tool, feature, or card

For Flag:

• [Name of tool or feature] check
• Reference check

For Recommend:

• Suggested [type of output]
• Suggested articles
• Suggested articles for you
• Suggested links

For Generate:

• Machine [type of output]
• Machine translation

Labels & Icon

Labels are optional. Use them when they clarify the nature of the output.

The robot icon may support machine-related labeling, but they should not replace clear text.

If you can only choose one, prefer a text label over an icon. Text is easier to understand across audiences and contexts.

For Flag and Recommend:

• No label necessary
• Optional: “Identified by a [description] model” (and linking to the model card)

If your use case is akin to spellcheck, grammar tools, or algorithmic recommendations, skip the label.

For Generate:

• Use “Identified by a [description] model” (and linking to the model card)

Given Wikipedia’s value in human-created content, be explicit in labeling machine-created content.

Disclaimers

Disclaimers are messages on the potential inaccuracy of machine-assisted outputs and what people can do.

Do you need a disclaimer?

For Flag:

• For readers: no
• For editors: it depends. Use one when the check or flag leads to a mandatory change or automated action

For Recommend:

• For readers: no, but include a feedback mechanism with optional info trail
• For editors: yes, include a disclaimer in the how-to or instructions description

For Generate:

• Yes, you need a disclaimer

Basic pattern

Machine [type of output] can be wrong or incomplete. [How the output can be wrong.] [Action: what the person can do.]

Variants

• [Feature name] is an experiment. [Type of output] can be wrong or incomplete.
• Machine [type of output] can be wrong or incomplete. [Action.]
• Machine [type of output] can be wrong. Check important information.

Examples

• Machine translations can be wrong or incomplete. Check important information.
• Suggestions can be wrong. The image may be unrelated to the section, low quality, or something else. You can add, reject, or skip an image if you’re not sure.

Feedback

Feedback mechanisms are important for Generate mode and crucial in use cases that involve the system taking automated actions.

Mechanisms to consider:

• Close action “X” to discard a suggestion
• Yes/no short question: Was this summary helpful?
• Drop-down menu of options
• Form or email for human review

When possible, explain how feedback will be used.

Examples:

• Your feedback will improve future suggestions.
• Feedback is anonymized and reviewed by [topic editors].
• Why is the link wrong?

Avoid thumbs up-thumbs down scales.

Buttons

Buttons should describe the action or outcome clearly.

Do

• Use sentence case.
• Keep English labels to one or two words when possible.
• Match the button wording to the card or dialog title.
• Use verbs for actions.

Don't

• Use a generic Submit when a clearer action is possible.
• Add machine-specific icons to buttons when the surrounding UI already provides that context.
• Use see when read, show, or view is more inclusive.

Examples:

• Add image
• Check facts
• Generate list
• View details
• Write caption

Links

Links should be descriptive and easy to understand out of context.

Do

• Make the link text say what the user will learn.
• Use “Learn more about [topic]” when needed.

Don't

• Use vague links that lose meaning when read on their own.

For “Learn more”, when possible, specify what people will learn about.

Example:

• Learn more about machine suggestions

Copywriting tips

Use this checklist before publishing machine-assisted copy.

• Is the focus on the user’s task?
• Is the explanation proportional to the risk?
• Is the language plain, neutral, and translatable?
• Is machine assistance disclosed at the right level for the use case?
• Are generated outputs labeled clearly when needed?
• Is there a feedback path when the use case needs one?