solving documentation minor problems #10240
Conversation
…d, decoding html a tag errors , Seperating Table headers, Making spaces constand, adding new words for clarity as a.k.a as formely known
DilshadNaleem
requested review from
chamilaadhi and
tharikaGitHub
as code owners
|
|
WalkthroughDocumentation files in the get-started section are being cleaned and simplified. A key concepts table is being restructured from an anchor-enhanced, multi-column dense format into a streamlined markdown table with shortened descriptions. A companion overview file receives minor formatting and text adjustments. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✨ 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.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
en/docs/get-started/overview.md (1)
30-30: Missing closing anchor tags in list items require fixing.Multiple list items contain unclosed anchor tags:
- Line 30:
<a href="...">Search</li>(missing</a>)- Line 47:
<a href="...">API documentation</li>(missing</a>)- Line 64:
<a href="...">API security</li>(missing</a>)- Line 81:
<a href="...">Rate limiting usecases</li>(missing</a>)- Line 98:
<a href="...">Observability</li>(missing</a>)- Line 99:
<a href="...">API Manager Analytics</li>(missing</a>)These break HTML structure and should be closed consistently with line 13's fix.
Apply this diff to fix all anchor tags:
- <li><a href="{{base_path}}/consume/discover-apis/search/">Search</li> + <li><a href="{{base_path}}/consume/discover-apis/search/">Search</a></li>- <li><a href="{{base_path}}/manage-apis/design/api-documentation/add-api-documentation/">API documentation</li> + <li><a href="{{base_path}}/manage-apis/design/api-documentation/add-api-documentation/">API documentation</a></li>- <li><a href="{{base_path}}/manage-apis/design/api-security/api-authentication/api-authentication-overview/">API security</li> + <li><a href="{{base_path}}/manage-apis/design/api-security/api-authentication/api-authentication-overview/">API security</a></li>- <li><a href="{{base_path}}/manage-apis/design/rate-limiting/introducing-throttling-use-cases/">Rate limiting usecases</li> + <li><a href="{{base_path}}/manage-apis/design/rate-limiting/introducing-throttling-use-cases/">Rate limiting usecases</a></li>- <li><a href="{{base_path}}/observe/observe-overview/">Observability</li> + <li><a href="{{base_path}}/observe/observe-overview/">Observability</a></li>- <li><a href="{{base_path}}/monitoring/api-analytics/choreo-analytics/getting-started-guide">API Manager Analytics</li> + <li><a href="{{base_path}}/monitoring/api-analytics/choreo-analytics/getting-started-guide">API Manager Analytics</a></li>Also applies to: 47-47, 64-64, 81-81, 98-98, 99-99
🧹 Nitpick comments (1)
en/docs/get-started/key-concepts.md (1)
23-23: Hyphenate compound adjective for clarity.Line 23 uses "rate limiting policy management" where "rate limiting" is a compound adjective modifying "policy management." For consistency with standard English grammar, use a hyphen: "rate-limiting policy management".
Apply this diff:
-| **Admin Role** | The user responsible for managing the Admin Portal, handling tasks such as workflow approvals, rate limiting policy management, and general administrative tasks (users, roles, security). | +| **Admin Role** | The user responsible for managing the Admin Portal, handling tasks such as workflow approvals, rate-limiting policy management, and general administrative tasks (users, roles, security). |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
en/tools/__pycache__/version_hook.cpython-312.pycis excluded by!**/*.pyc
📒 Files selected for processing (2)
en/docs/get-started/key-concepts.md(1 hunks)en/docs/get-started/overview.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
en/docs/get-started/key-concepts.md
[uncategorized] ~23-~23: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...dling tasks such as workflow approvals, rate limiting policy management, and general administ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (4)
en/docs/get-started/overview.md (3)
1-1: Trailing space in title may be unintentional.Line 1 has a trailing space after "Overview". Verify this is intentional formatting and not a stray character.
3-3: Comma removal improves clarity.Removing the comma before "and" in "API Products and endpoints" aligns with standard punctuation for coordinating conjunctions and improves readability.
13-13: Anchor tag properly closed.The Design API Overview link now has a properly closed anchor tag with consistent internal spacing, improving HTML structure consistency.
en/docs/get-started/key-concepts.md (1)
3-22: Excellent restructure improves clarity and comprehensiveness.The migration from a complex multi-column table to a clean markdown format significantly improves readability. Bold key concepts, refined descriptions, and structured layout align well with PR objectives:
- All main concepts are bolded for emphasis (objective #2)
- Phrasing updated from "a.k.a Swagger" to "formerly known as Swagger" (objective #6)
- Access Token definition now clarifies authorization as permission (objective #7)
The simplified descriptions maintain technical accuracy while being more scannable.
|
Hi @DilshadNaleem, Will you be able to add a screenshot for the changes done to the file Also the |
|
Hello madam,
these are the images done by me yesterday.
Notes:
1.
Under Overview there is comma after "API Products and, endpoints" word
2.
Making the main heads in bold for the classifications.
3.
Decoding html a tag errors inside the table.
4.
Making space constantly through out the page.
5.
Adding new words for extra clarity to maintain the professional manner.
…________________________________
From: Tharika Madurapperuma ***@***.***>
Sent: Thursday, November 6, 2025 04:08 PM
To: wso2/docs-apim ***@***.***>
Cc: Dilshad Naleem ***@***.***>; Mention ***@***.***>
Subject: Re: [wso2/docs-apim] solving documentation minor problems (PR #10240)
[https://avatars.githubusercontent.com/u/8557410?s=20&v=4]tharikaGitHub left a comment (wso2/docs-apim#10240)<#10240 (comment)>
Hi @DilshadNaleem<https://github.com/DilshadNaleem>,
Will you be able to add a screenshot for the changes done to the file en/docs/get-started/key-concepts.md to see how it would look like now?
—
Reply to this email directly, view it on GitHub<#10240 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BIPEZ335T6QHWAJQNBQ5H5333MQJZAVCNFSM6AAAAACLCYK6L2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIOJWGQ3TEOBTGU>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
|
Hi @DilshadNaleem, the images are not visible in your comment above. Just a single screenshot of the key concepts page would be sufficient. Will you be able to add one? |
|
[cid:deea0459-b381-43b7-9eca-e36e6510014a]
[cid:b2a911d1-0ae4-43ee-831a-cec438aac90f]
Madam there is a small issue, I couldn't submit the CV it shows an error message "Failed to send API call to choreo".
…________________________________
From: Tharika Madurapperuma ***@***.***>
Sent: Friday, November 7, 2025 12:14 PM
To: wso2/docs-apim ***@***.***>
Cc: Dilshad Naleem ***@***.***>; Mention ***@***.***>
Subject: Re: [wso2/docs-apim] solving documentation minor problems (PR #10240)
[https://avatars.githubusercontent.com/u/8557410?s=20&v=4]tharikaGitHub left a comment (wso2/docs-apim#10240)<#10240 (comment)>
Hi @DilshadNaleem<https://github.com/DilshadNaleem>, the images are not visible in your comment above. Just a single screenshot of the key concepts page would be sufficient. Will you be able to add one?
—
Reply to this email directly, view it on GitHub<#10240 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BIPEZ35D5AOLBVNHJ5RGMAT33Q5U7AVCNFSM6AAAAACLCYK6L2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKMBQHE4DKNJRG4>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
|
Hi @DilshadNaleem, it could be because you are trying to reply via email. Shall we comment directly on the git issue if possible? |
Notes:
|
|
Ok madam its done. Sorry
…________________________________
From: Tharika Madurapperuma ***@***.***>
Sent: Friday, November 7, 2025 12:30 PM
To: wso2/docs-apim ***@***.***>
Cc: Dilshad Naleem ***@***.***>; Mention ***@***.***>
Subject: Re: [wso2/docs-apim] solving documentation minor problems (PR #10240)
[https://avatars.githubusercontent.com/u/8557410?s=20&v=4]tharikaGitHub left a comment (wso2/docs-apim#10240)<#10240 (comment)>
Hi @DilshadNaleem<https://github.com/DilshadNaleem>, it could be because you are trying to reply via email. Shall we comment directly on the git issue if possible?
—
Reply to this email directly, view it on GitHub<#10240 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BIPEZ377VTOSETYVWWVUXGD33Q7RVAVCNFSM6AAAAACLCYK6L2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKMBRGAZDINBZGQ>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
3 participants
in /get-started/overview/ in the first paragraph it says API products, and endpoints -> removing the , after the word And.
Making the main things in bold for easy visualization.
Arranging the HTML a tags for clear visualization without messing it with standard documentation practice.
A Separator is present, but the standard Markdown uses dashes to match the column.
There are some inconsistent spacing and extra black spaces, particularly around the anchor-tagged items.
Changing the OAS, a.k.a Swagger to clarity improvements as formerly known as Swagger.
Clarifying the token's role in authorization.
Summary by CodeRabbit
Release Notes