docs: Content improvement in SMS OPT and Email OTP documentation#5916
docs: Content improvement in SMS OPT and Email OTP documentation#5916KethniiImasha wants to merge 7 commits intowso2:masterfrom
Conversation
WalkthroughQuick-start documentation updated: introductory sentence reworded, product blurb adjusted (consistent "API Security" capitalization), an embedded YouTube iframe added to the hero/media area, several minor grammar and formatting tweaks (bullet punctuation, blank-line adjustments, extra horizontal rule). Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
en/identity-server/next/docs/get-started/quick-start-guide.md (4)
19-19: Make the role description more direct.This can be more concise and active.
✅ Proposed edit
-- **Data Protection Officers** who need to implement and monitor a system that adheres to privacy protection regulations across the organization. +- **Data Protection Officers** who implement and monitor privacy compliance across the organization.As per coding guidelines, "Use plain language and short sentences" and "Use precise nouns and strong verbs; avoid vague verbs such as handle, manage, deal with, perform, and utilize".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/get-started/quick-start-guide.md` at line 19, Replace the passive, wordy role description for "Data Protection Officers" with a concise, active sentence; locate the line containing the phrase "Data Protection Officers" and change it to a short, direct statement such as "Data Protection Officers ensure the organization complies with privacy and data protection regulations," using precise nouns and strong verbs and keeping the sentence short and plain.
29-29: Tighten the SSO bullet and address the reader.This sentence is long and ends with a run‑on clause.
✅ Proposed edit
-- **Unify sign-ins** - WSO2 IS facilitates single sign-on (SSO) that eliminates the need to maintain multiple credentials for each application making life easier for your users. +- **Unify sign-ins** - WSO2 IS provides single sign-on (SSO) so you do not maintain separate credentials for each application.As per coding guidelines, "Use plain language and short sentences" and "Address the reader as 'you'".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/get-started/quick-start-guide.md` at line 29, The bullet "Unify sign-ins" is a long run-on sentence and doesn't address the reader; rewrite it to be short, use plain language, and address the reader as "you" (e.g., change the sentence that begins "WSO2 IS facilitates single sign-on..." to something concise like "Unify sign-ins — With WSO2 IS, you get single sign-on (SSO) so you don't need separate credentials for each app."). Ensure the revised text replaces the existing "Unify sign-ins" bullet and keeps the original intent about SSO while using "you" and a shorter, clearer sentence.
5-5: Shorten and de‑market the product description.This sentence is long, uses “a variety of,” and ends with “so much more.” Consider two shorter, direct sentences.
✅ Proposed edit
-**{{ product_name }} (WSO2 IS)** simplifies the Customer Identity and Access Management (CIAM) needs of your organization. The product ensures easy integration with a variety of applications to facilitate single sign-on (SSO), social login, identity federation, API Security, strong authentication, account management, privacy compliance, and so much more. +**{{ product_name }} (WSO2 IS)** simplifies the Customer Identity and Access Management (CIAM) needs of your organization. It helps you integrate with many applications and supports single sign-on (SSO), social login, identity federation, API Security, strong authentication, account management, and privacy compliance.As per coding guidelines, "Use plain language and short sentences" and "Keep a professional, friendly, neutral tone and avoid slang, jokes, sarcasm, and marketing language".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/get-started/quick-start-guide.md` at line 5, Replace the long marketing sentence for {{ product_name }} (WSO2 IS) with two short, plain-language sentences that remove promotional phrasing like "a variety of" and "so much more"; e.g., state what the product does (CIAM, SSO, social login, identity federation, API security, strong authentication, account management, privacy compliance) in one concise sentence and follow with a second neutral sentence about integration with applications or deployment scenarios, ensuring tone is professional and de‑marketed.
3-3: Use direct, reader-focused phrasing.“what we offer” reads like marketing and does not address “you.” Consider a direct, present-tense line.
✅ Proposed edit
-Are you new to **{{ product_name }}**? Let's learn more about what we offer! +Are you new to **{{ product_name }}**? Learn how you can get started.As per coding guidelines, "Use active voice and present tense; use passive voice only when the actor is unknown or unimportant" and "Address the reader as 'you'".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/get-started/quick-start-guide.md` at line 3, The headline "Are you new to **{{ product_name }}**? Let's learn more about what we offer!" uses passive/marketing phrasing; change it to a direct, present-tense, reader-focused line that addresses the user (e.g., start with "New to {{ product_name }}?" or "Get started with {{ product_name }}") and follow with an active present-tense benefit or action. Update the line in the quick-start guide (the string beginning "Are you new to **{{ product_name }}**?") to use active voice and "you"-addressing language.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@en/identity-server/next/docs/get-started/quick-start-guide.md`:
- Line 19: Replace the passive, wordy role description for "Data Protection
Officers" with a concise, active sentence; locate the line containing the phrase
"Data Protection Officers" and change it to a short, direct statement such as
"Data Protection Officers ensure the organization complies with privacy and data
protection regulations," using precise nouns and strong verbs and keeping the
sentence short and plain.
- Line 29: The bullet "Unify sign-ins" is a long run-on sentence and doesn't
address the reader; rewrite it to be short, use plain language, and address the
reader as "you" (e.g., change the sentence that begins "WSO2 IS facilitates
single sign-on..." to something concise like "Unify sign-ins — With WSO2 IS, you
get single sign-on (SSO) so you don't need separate credentials for each app.").
Ensure the revised text replaces the existing "Unify sign-ins" bullet and keeps
the original intent about SSO while using "you" and a shorter, clearer sentence.
- Line 5: Replace the long marketing sentence for {{ product_name }} (WSO2 IS)
with two short, plain-language sentences that remove promotional phrasing like
"a variety of" and "so much more"; e.g., state what the product does (CIAM, SSO,
social login, identity federation, API security, strong authentication, account
management, privacy compliance) in one concise sentence and follow with a second
neutral sentence about integration with applications or deployment scenarios,
ensuring tone is professional and de‑marketed.
- Line 3: The headline "Are you new to **{{ product_name }}**? Let's learn more
about what we offer!" uses passive/marketing phrasing; change it to a direct,
present-tense, reader-focused line that addresses the user (e.g., start with
"New to {{ product_name }}?" or "Get started with {{ product_name }}") and
follow with an active present-tense benefit or action. Update the line in the
quick-start guide (the string beginning "Are you new to **{{ product_name
}}**?") to use active voice and "you"-addressing language.
|
Hi @chamilaadhi, I have updated the terminology to 'sign-in' and ensured the use of active voice and present tense throughout. All formatting and indentation issues are now resolved. I am applying for the WSO2 Engineering Internship, and this PR is part of my contribution toward that. Could you please review when you have a moment? Thank you. |
|
Hi @pavinduLakshan, I'm checking in to see if you could take a look at this PR when you have a moment. It also looks like the automated workflows need a maintainer's approval to run. Thank you. |
|
Hi @KethniiImasha, related PRs section in the PR description is for the pull requests that are directly related to the current pull request such as product improvement PRs relevant to the doc changes etc. the PR you have linked here is not a related PR in that sense. Please update the pr description accordingly. |
|
Hi @pavinduLakshan , thank you for the clarification! I have updated the PR description and removed the link to the other formatting PR. Let me know if everything looks correct now. |
KethniiImasha
changed the title
2 participants
Purpose
Resolves minor grammatical inconsistencies and standardizes technical casing (e.g., "API Security") in the Identity Server Quick Start Guide to improve readability for new users.
Related PRs
N/A
Test environment
Operating System: MacOS 15
Editor: VS Code (Markdown Preview)
Security checks
Summary by CodeRabbit