Product knowledge

Build shared product context for AI-assisted workflows.

Without product context, AI tools can produce output that sounds right but gets the details wrong, especially when your product uses terms that overlap with everyday language, or when internal shorthand doesn’t match customer-facing terminology.

Product knowledge is where you define that context in Atono. It allows you to generate and manage structured product concepts that can be used with AI tools across your workflows.



How product knowledge works

Product knowledge in Atono exists at two levels:

  • The Glossary provides shared, workspace-level context about your product, including its terminology, features, roles, and workflows.
  • AI context preserves context for an individual story or bug, including decisions, investigation findings, implementation changes, and test planning as the work progresses. For more details, see AI context.

Together, they give people and AI tools both the broader product context and the context specific to the work at hand.



Glossary

The Glossary helps AI tools understand your product's terminology, features, roles, and workflows. By giving AI a shared source of product context, you can generate more accurate stories, documentation, implementation plans, and other work products.

The Glossary builds a structured list of your product's key concepts from documentation sources or an uploaded glossary file. It includes concepts such as feature names, workflows, screens, roles, and domain-specific language, and organizes them into a reusable reference.

There's one shared Glossary per workspace. Rebuilding or replacing it updates the Glossary for everyone in the workspace.

Each Glossary entry may include:

  • Concept: The fully spelled-out concept name. Each name is unique.
  • Description: A concise, plain-English description written to be efficient for AI usage.
  • Synonyms: Alternate names or abbreviations found in your documentation.
  • Related concepts: Links to other Glossary entries that are closely related.

View the Glossary

If a Glossary has already been built for your workspace, you can open it to browse existing concepts. The 'Glossary' panel shows the total number of concepts and when the Glossary was created.

  1. In the navigation menu, click Product knowledge.
  2. In the 'Glossary' panel, click View.

Concepts are grouped alphabetically by name. Use the alphabetical jump bar at the top of the 'Concepts' tab to quickly move to a particular section of the Glossary. Click a letter to jump to the first concept beginning with that letter. Letters without any concepts are unavailable. If any concept names begin with a number or special character, click # to jump to those concepts.


Search the Glossary

Locate a concept by searching for a keyword in its name or description.

  1. Click the search (magnifying glass) icon at the top of the Glossary.
  2. Enter a search term. The Glossary automatically updates to show matching concepts with the search term highlighted in its name or description.

Build the Glossary

Anyone in your workspace can build the Glossary. Whoever builds it automatically receives Glossary Owner permissions.

Building the Glossary generates a structured list of product concepts for your workspace. You can either crawl documentation URLs or upload a glossary in TSV format.

  1. In the navigation menu, click Product knowledge.
  2. Click Build glossary.
  3. Optionally, enter your product name in the 'Product name' field.
    • If your product name overlaps with a common word, adding it here helps reduce ambiguity during Glossary generation.
  4. Under 'Glossary source', select one of the following:
    • Crawl documentation
    • Upload glossary file

Crawl documentation

  1. Select Crawl documentation.
  2. Paste one or more URLs in the 'Documentation URLs' field.
    • Good sources include help documentation, knowledge bases, and user or admin guides.
    • You can add multiple URLs if your documentation spans sections.
📘

Tip: Use root-level URLs for better coverage

Atono crawls your documentation starting from the URLs you provide. For best results, enter a root-level URL (parent path), not a single article page.

For example:

  • https://docs.example.com/docs/welcome-to-product may crawl only that page.
  • https://docs.example.com/docs is more likely to crawl that section and the pages beneath it.

Recommendation: Use the highest-level URL that represents the section you want included in your glossary.

  1. Click Build glossary to begin processing.

Building the Glossary may take up to 20 minutes. Atono shows progress while it runs. You can navigate away, and when the build completes or fails, Atono displays a notification with the result.


Upload a glossary file

Use a glossary TSV file when your documentation cannot be crawled by Atono.

📘

Tip: Download a template

Click Download template to download a TSV file containing the required columns.

  1. Select Upload glossary file.
  2. Drag and drop a TSV file into the upload area, or click browse files.
  3. Verify that the file meets the requirements:
    • TSV format
    • Maximum file size of 1 MB
    • Required columns: 'Concept', 'Definition', 'Synonyms', and 'Related concepts'
  4. Click Build glossary to begin processing.

If the uploaded file doesn't meet the requirements, Atono displays an error and disables 'Build glossary' until the issue is corrected.


View sources and status

The 'Sources' tab shows the sources used to generate your Glossary, when they were processed, and whether they were successfully imported or retrieved.

  1. In the navigation menu, click Product knowledge.
  2. In the 'Glossary' panel, click View.
  3. Click the Sources tab.
  4. Review the list of Glossary sources.
  5. Click a source row to expand it and view additional details.

Documentation sources

Documentation sources display:

  • Source: The URL you entered.
  • Status: How many URLs were crawled and whether any retrieval failures occurred.
  • Last refreshed: When the source was last refreshed.

If a source fails, it shows a 'Failed' status. Glossary generation can still succeed as long as most sources are retrieved successfully.


Uploaded glossary files

Uploaded glossary files display:

  • Source: The uploaded filename.
  • Status: The number of concepts loaded and any warnings generated during import.
  • Uploaded: When the file was imported.

If warnings are generated, expand the source row to review them.

Warnings identify the affected concept and the reason for the warning, such as:

  • Definition truncated to 500 characters.
  • Duplicate concept skipped.
  • Related concept not found.

Export the Glossary

When the Glossary has entries, the 'Export glossary' option is available.

  1. Open the Glossary.
  2. Click the ellipsis (...) icon and select Export glossary.

Exports are in TSV (tab-separated values) format and include a header row with the following columns:

  • Concept
  • Definition
  • Synonyms
  • Related concepts

You can use this export as structured context in AI workflows when your tool doesn't connect to the Atono MCP server, for example, when drafting stories, generating documentation, or planning code.

You can also use an exported glossary as a starting point for future glossary uploads.


Use the Glossary with AI tools

You can use the Glossary as product context when working with AI tools. This helps the AI interpret product terminology, features, roles, and workflows more consistently.

If your AI tool is connected to the Atono MCP server, it can retrieve the latest published Glossary directly from your workspace. This is the recommended option when available because it uses the current Glossary without requiring a manual export.

Use a TSV export when you need a static copy of the Glossary or when your AI tool doesn't support the Atono MCP server.

Some ways to use Glossary context with AI tools:

  • Retrieve the Glossary through the Atono MCP server before drafting stories or implementation plans.
  • Export the Glossary as a TSV file and provide it to an AI tool as structured context.
  • Include Glossary context when generating acceptance criteria, reviewing edge cases, drafting documentation, or working with AI coding assistants.
  • Use the Story assistant to write and review stories. It uses the Glossary automatically, and story reviews check a story's terminology and behavior against it.

Refresh the Glossary

Only Glossary owners, Workspace Owners, Administrators, and Product Managers can refresh the Glossary.

Refreshing the Glossary reprocesses your documentation sources to find meaningful updates from your documentation. Atono looks for new key concepts, updates to existing concepts, and concepts that may no longer apply.

🚧

A Glossary created from an uploaded TSV file can't be refreshed. To update it, delete the Glossary and build a new one from an updated TSV file.

  1. Open the Glossary.
  2. On the 'Sources' tab, click Refresh glossary.

While the refresh is running, manual edits to Glossary concepts are temporarily blocked. You can still view the Glossary, export it, and manage its permissions.

When the refresh completes, the Glossary reflects any confirmed changes from the source:

  • Newly identified key concepts are added.
  • Existing concepts are updated only when clearly supported by the source.
  • Concepts that no longer apply are removed.

Deleted concepts remain excluded from future refreshes unless restored.


When to refresh the Glossary

The Glossary reflects the documentation it was generated from. If your product or docs change, refreshing helps keep AI output aligned with your current terminology.

Refresh the Glossary when:

  • Major features are added or renamed.
  • Core workflows change.
  • Terminology shifts between internal and customer-facing language.
  • Help documentation is significantly updated.


Manage the Glossary

In addition to building the Glossary automatically from documentation, you can manually add, edit, delete, and restore individual concepts to keep your Glossary accurate as your product evolves.

As you make changes, Atono tracks updates to each concept over time, so you can review version history and undo or restore changes when needed. For more details, see Track and manage changes.

Only Workspace Owners, Administrators, Product Managers, and users with Glossary Owner or Contributor permissions can manage concepts. All other users have a read-only view.


Add a concept

Add a concept manually when a term is missing from the generated Glossary or needs to be defined in a way that better reflects your product's usage.

  1. Open the Glossary.
  2. On the 'Concepts' tab, click Add concept.
  3. Enter the concept's name and description in the 'Name' and 'Description' fields.
  4. Optionally, add one or more synonyms in the 'Synonyms' field as a comma-separated list.
  5. Optionally, add any related concepts in the 'Related concepts' field by selecting from existing Glossary concepts. To remove a related concept, click the X on the concept pill.
  6. Click Add, or click Cancel or X to discard.

Edit a concept

Edit a concept to update its name, description, synonyms, or related concepts.

  1. Open the Glossary.
  2. On the 'Concepts' tab, click the ellipsis (...) icon next to the name of the concept you want to edit.
  3. From the menu, select Edit.
  4. Modify the concept details.
  5. Click Save, or click Cancel or X to discard.

Delete a concept

Delete a concept to remove it from the Glossary. Deleted concepts are moved to the 'Deleted concepts' page, where they're excluded from future Glossary refreshes. You can restore a deleted concept at any time.

  1. Open the Glossary.
  2. On the 'Concepts' tab, click the ellipsis (...) icon next to the name of the concept you want to delete.
  3. From the menu, select Delete.
  4. In the confirmation dialog, click Delete to confirm, or click X to cancel.

You can also delete a concept from within the edit view.


Restore a concept

Deleted concepts are saved on the 'Deleted concepts' page. Concepts listed here are excluded from Glossary refreshes. If someone tries to manually add a concept with the same name as a deleted concept, Atono will prompt them to restore it instead.

The 'Deleted concepts' list includes each concept's name, which user deleted it (or '✦ AI' if it was removed automatically during a Glossary refresh), and when it was deleted.

  1. Open the Glossary.
  2. Click the ellipsis (...) icon next to the Glossary title.
  3. From the menu, select Deleted concepts.
  4. On the 'Deleted concepts' page, click Restore next to the concept you want to add back.


Track and manage changes

As you add and refine concepts, Atono keeps a record of every change made to your Glossary. This includes changes made manually and those created when the Glossary was first built or refreshed.

You can review these changes, understand how a concept has evolved over time, and revert changes when needed, either across multiple concepts or within a single one.

Changes made during a Glossary refresh are grouped together in the 'History' tab. You can review these changes as a set or undo them all at once, or undo individual changes within the group.

Only Workspace Owners, Administrators, Product Managers, and users with Glossary Owner or Contributor permissions can view change history, including the 'History' tab and version history. Other users won't see these options.


View change history

The 'History' tab shows a list of changes made to your Glossary. Each entry represents a single change to a concept, including additions, edits, and deletions. For each change, you'll see the concept name, the type of change, who made it, and when it occurred. Concepts imported from a glossary TSV file appear as additions with a source of 'Upload'.

Open the Glossary and click the History tab.

Use this view to scan recent activity and identify changes you may want to review or undo. To see the details of a change, click an entry to open the concept and view its version history.

As changes build on each other, some entries include additional context to show how they relate to other updates. For example, you may see when a concept was last edited, when a version was restored, or when a change was later reversed. These details help clarify which version is current and how the concept has evolved over time.


Sort the list

By default, changes are shown in reverse chronological order, with the most recent activity at the top. Click History at the top of the table to toggle between newest-first and oldest-first.


Filter the list

You can filter the list to focus on specific types of changes or sources. Click Filter by to refine the results:

  • Type: Shows only additions, edits, or deletions.
  • Source: Shows changes made by AI, uploads, or users.

Review changes to a concept

Open a concept from the 'History' tab or the 'Concepts' tab to view its version history.

In the concept detail panel, click Version history.

The version history shows all previous versions of the concept, with changes highlighted between each version. This view is useful when you want to closely inspect how a concept has evolved before restoring it.


Restore or undo changes

You can revert changes in two ways, depending on your starting point.


Restore a previous version

Use this when reviewing a single concept.

From the version history, select the version you want to restore and click Restore version. Confirm the action to create a new current version using the selected content. Earlier versions are preserved, so you can continue to move backward or forward through the concept's history if needed.


Undo recent changes

Use this when working from the 'History' tab.

Undo allows you to revert recent changes directly from the History list without opening each concept individually. This is useful when reviewing recent updates or correcting changes across multiple concepts.


Undo multiple changes

From the 'History' tab, you can select multiple changes and undo them in a single action.

Select one or more eligible entries to activate the bulk action bar, then click Undo.

Only the most recent change to a concept can be selected. If a newer change exists, the checkbox is disabled. To revert an earlier change, undo the more recent changes first, or restore a specific version from the concept's version history.

Each change is undone based on its type. Additions are reversed by removing the concept, edits are rolled back to the previous version, and deletions restore the concept.

Before undoing the selected changes, you'll be asked to confirm the action. The confirmation summarizes the changes and what will happen to each one. Once confirmed, the History list and any affected concepts update to reflect the reverted changes.


Glossary refresh changes

Changes made during a Glossary refresh are grouped together in the 'History' tab. This makes it easier to review related updates and undo them together.

Each refresh shows a summary of changes, including how many concepts were added, edited, or deleted. Expand a refresh to review individual changes, grouped by type.


Undo a Glossary refresh

You can undo changes from a Glossary refresh in two ways:

Undo the entire refresh

On the refresh summary in the 'History' tab, click Undo to revert all of the refresh's changes: added concepts are deleted, edited concepts revert to their previous version, and deleted concepts are restored. The Glossary returns to its previous state, and the refresh and its changes are removed from history.

Only the most recent Glossary refresh can be undone this way. If changes have been made after the refresh, bulk undo is not available.

Undo individual changes

Expand the refresh to view individual changes. Select and undo specific additions, edits, or deletions. Individual changes can be undone regardless of whether bulk undo is available.



Glossary permissions

Glossary permissions control who can manage concepts and perform actions like refreshing or deleting the Glossary. All workspace users can view the Glossary regardless of their permission level.


Glossary permission types

When you build the Glossary, you automatically receive Owner permissions. As an owner, you can add or remove permissions for other users in your workspace.

  • Contributor: Glossary contributors can manually add, edit, delete, and restore Glossary concepts.
  • Owner: Glossary owners have the same capabilities as contributors, but only they can refresh and delete the Glossary.

Workspace Owners, Administrators, and Product Managers have the same abilities as Glossary owners, without explicitly requiring Owner permissions.


Grant Glossary permissions

Only Workspace Owners, Administrators, Product Managers, and users with Glossary Owner permission can assign permissions to other users.

  1. On the Glossary page, click the ellipsis (...) icon.
  2. From the menu, select Glossary permissions.
  3. In the 'Glossary permissions' dialog, search for the users you want to grant permissions to.
  4. Select Owner or Contributor.
  5. Click Add.
  6. Repeat as needed, then click Done when finished.

Change a user's permissions

Only Workspace Owners, Administrators, Product Managers, and users with Glossary Owner permissions can change the permissions for other users. You can't modify your own permissions.

  1. On the Glossary page, click the ellipsis (...) icon.
  2. From the menu, select Glossary permissions.
  3. In the 'Glossary permissions' dialog, modify the permission level in the 'Glossary permission' column.
  4. Click Done.

Remove Glossary permissions

Only Workspace Owners, Administrators, Product Managers, and users with Glossary Owner permission can remove the permissions for other users. You can't modify your own permissions.

  1. On the Glossary page, click the ellipsis (...) icon.
  2. From the menu, select Glossary permissions.
  3. In the 'Glossary permissions' dialog, hover over the user you want to remove and click the ellipsis (...) icon.
  4. From the menu, select Remove.


Delete the Glossary

Only Glossary owners, Workspace Owners, Administrators, and Product Managers can delete the Glossary.

Deleting the Glossary permanently removes all Glossary concepts from your workspace. Delete it when you want to rebuild from updated documentation or different sources.

  1. In the navigation menu, click Product knowledge.
  2. In the 'Glossary' panel, click View.
  3. Click the ellipsis (...) icon.
  4. Select Delete glossary.
  5. In the confirmation dialog, click Delete glossary to confirm, or click X to cancel.

After deleting the Glossary, click Build glossary to generate a new one.



Did this page help you?