Skip to content

Consistent terminology and concepts - after a Claude review#575

Open
lisa-tarbo wants to merge 13 commits into
mainfrom
terminology-and-concepts
Open

Consistent terminology and concepts - after a Claude review#575
lisa-tarbo wants to merge 13 commits into
mainfrom
terminology-and-concepts

Conversation

@lisa-tarbo

@lisa-tarbo lisa-tarbo commented Jul 18, 2026

Copy link
Copy Markdown
Collaborator

Background

To assist easy understanding of concepts, keep terminology consistet

Used Claude to double check consistency of the main terminology.
This resolves #574
Checklist of issues fixed in the Issue

Reviewer Notes

  1. "User" is the user of OCS.
  2. "Participant" is the person chatting with the chatbot

lisa-tarbo and others added 10 commits July 18, 2026 13:58
@lisa-tarbo @claude
Add LLM Service Provider and Speech Service Provider glossary terms
41e7e75 
The concepts glossary only defined Authentication Provider and
Messaging Provider, but the UI has 5 distinct provider settings
pages. Add the two missing ones so docs consistently distinguish
provider types.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Align sessions.md terminology with glossary (Participant, Chatbot)
8a8fc70 
sessions.md defined a rival "User" term that duplicated the glossary's
Participant concept, and used "user"/"bot" throughout instead of the
canonical "participant"/"chatbot".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Stop calling Custom Actions "tools" in docs
3d7072c 
Custom Actions and Tools are distinct glossary concepts, but two pages
called a Custom Action a "tool", contradicting the glossary's
distinction between the two.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Use "team" instead of "workspace" in deploy_email_channel.md
3d75636 
The glossary term is "Team"; "workspace" doesn't match any UI label
and only appeared in this one page.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Disambiguate "platform" from Channel and from OCS itself
aace58e 
"platform" was used for the Channel concept, and separately for OCS
itself, with no way to tell which was meant. Link to the Channel
concept on first use, and say "Open Chat Studio" where that's what
was meant.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Qualify LLM Service Provider naming and fix bot->chatbot wording
0fd82fe 
Align configure_providers.md's title and intro with the new "LLM
Service Provider" glossary term, and fix a stray "bot" reference.
Also fix casing on the Tracing Providers list item in team/index.md
for consistency with its siblings.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Use "publish" instead of "release" in versioning_steps.md
f783c1b 
Matches the tutorial's own "Set as Published Version" action and the
Versions glossary term, avoiding a third synonym for the same action.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Replace generic "bot" with "chatbot" in narrative prose
c0ed457 
Across events, session_status, tags, tracing, prompt_variables,
python_node, tools, workflow_cookbook, send_email_node, and
collections docs, informal "bot" wording didn't match the glossary's
"Chatbot" term. Bolded trigger/action labels that mirror literal
StaticTriggerType/EventActionType option text (e.g. "New Bot
Message") are left untouched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Replace generic "user" with "participant" in narrative prose
ba51e17 
Across channels.md, deploy_to_different_channels.md, and
python_node.md, "user" was used for the person chatting with a
chatbot, which the glossary calls "Participant" (reserving "user" for
an OCS account holder). The user_input dict key name is left
unchanged since it's a literal field name.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lisa-tarbo @claude
Fix broken anchor link after workflow_cookbook.md heading rename
470befb 
The Section 10 terminology pass renamed the "Split bot into multiple
smaller bots" heading, which changed its auto-generated anchor slug.
Caught by zensical build --strict.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@claude

claude Bot commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

Review: terminology consistency

Nice, high-value cleanup. The bot→chatbot, workspace→team, and platform→Open Chat Studio passes are solid, the two new glossary entries resolve correctly, and the workflow_cookbook heading rename + matching anchor update in history.md are consistent. A few gaps remain where the pass was partial — since the whole point is consistency, these are worth closing.

Introduced inconsistencies (worth fixing before merge)

  1. docs/tech-hub/custom_action/index.md:3 now says each operation 'appears as a selectable action in your chatbot's configuration', but line 12 of the same page still says operations 'appear as selectable tools', and docs/concepts/llm_custom_action.md:15 (also edited here) says they 'appear alongside Tools'. Three different framings of the same thing — pick one and use it in all three spots.

  2. docs/concepts/events.md (Event Actions list): 'Prompt the bot to message the user: Prompts the bot to message the user.' still says bot twice, while the sibling 'Trigger a schedule' bullet just below was updated to chatbot. Inconsistent within one list.

  3. docs/how-to/deploy_email_channel.md:3 — 'The email channel lets users interact with your chatbot…' directly contradicts the identical sentence in docs/how-to/deploy_to_different_channels.md, which was correctly changed to 'participants'. (Same file also missed: line 9, and the 'user to chatbot' attachment headings/prose — all refer to the person emailing, i.e. a participant.)

Misses in files this PR already edited

  1. docs/concepts/session_status.md:137 — '…as soon as the bot sends a specific goodbye message' was missed. Line 116's illustrative example 'end the session once the user confirms…' should be participant (the verbatim tool-description quote on line 105 stays as-is).
  2. docs/concepts/collections/index.md — 'sending them to users during a conversation' / 'send files to users' / 'takes effect for users immediately' describe the participant receiving files.
  3. docs/concepts/consent.md:3 — 'chatbot users' / 'displayed to users' mean participants.
  4. docs/concepts/team/llm_providers.md — now freshly linked from the new glossary entry, but still calls OCS 'the platform' (lines 5, 38, 40).

Optional

  • docs/concepts/versioning.md still uses 'release/released' as a verb (lines 62, 64) while versioning_steps.md was correctly moved to 'publish' (the UI term). Reconcile the concept page to match.
  • The OCS-user role is named three ways in edited files: 'chatbot builder' (python_node.md), 'chatbot developers' (tracing.md), 'chatbot makers' (consent.md). Pick one.
  • docs/concepts/index.md:113 (in the glossary block being edited) has a pre-existing 'An provider account' → 'A provider account'.

Note: 'user' inside literal LLM prompt templates (e.g. workflow_cookbook.md) is the standard prompt-role convention — leave those as-is.

@lisa-tarbo
lisa-tarbo marked this pull request as ready for review July 18, 2026 13:15
@lisa-tarbo
lisa-tarbo requested a review from SmittieC July 18, 2026 14:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@SmittieC SmittieC Awaiting requested review from SmittieC

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Terminology Consistency across all pages

1 participant

@lisa-tarbo