doc: Update the Segments setup instructions for Github (#2641)

* doc: Update the Segments setup instructions for Github

* clean: Fix some nitpicks

Author: nfcodacy

docs/organizations/segments.md

@@ -1,8 +1,10 @@
 # Segments
 
-_Segments are not supported for Personal orgs, as Custom Properties are not available in Github for these orgs._
+!!! important
+    Segments are not supported for Personal orgs, as Custom Properties are not available in GitHub for these orgs.
+
+Segments are dimensions that Codacy reads from your provider that organizes repositories into relevant groups for you. Today, Segments are available for:
 
-Segments are dimensions that Codacy reads from your provider that organizes repositories into relevant groups for you. Today, Segments is available for: 
 - [GitHub Custom Properties](#github-custom-properties)
 - [Bitbucket Projects](#bitbucket-projects)
 
@@ -21,13 +23,16 @@ To enable Segments, an initial sync between your provider and Codacy needs to ha
 ### GitHub Custom Properties {: id="github-custom-properties"}
 Custom properties allow you to assign tags or metadata to repositories, making it easier to categorize and filter them. Create, use, and manage custom properties for your repositories directly in GitHub. 
 
-> Refer to [GitHub's official documentation](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#adding-custom-properties) for detailed steps on how to add, edit, and manage repository **Custom Properties**. 
+> Refer to [GitHub's official documentation](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#adding-custom-properties) for detailed steps on how to add, edit, and manage repository **Custom Properties**.
 
 #### Keep Segments insync
 For changes to repository **Custom Properties** in GitHub to be **automatically** reflected in Codacy, users need to [accept the new permission request made by the Codacy GitHub app](https://docs.github.com/en/apps/using-github-apps/approving-updated-permissions-for-a-github-app). 
+
 !!! note
     If the permission is **not accepted**, users will still be able to use Repository Custom Properties as filters in Codacy, but will need to manually trigger a sync. This can be done using the **manual sync** button available in the filter dropdown, which allows users to synchronize changes from GitHub, though the process may take longer.
 
+Also, the target Custom Properties need to have the option **Allow repository actors to set this property** enabled in GitHub.
+
 ### Bitbucket Projects {: id="bitbucket-projects"}
 Bitbucket Projects allow you to organize your repositories into relevant contexts for you, making it easier to categorize and filter them. Create, use, and manage Projects for your repositories directly in Bitbucket.