Documenting x-state in the help center #319
Conversation
✅ Deploy Preview for bump-content-hub ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| Current definition URL. It should be accessible through HTTP by Bump.sh servers. | ||
| ``` | ||
|
|
||
| Adding or removing this property is a structural change. |
There was a problem hiding this comment.
structural change
I recommend that we clarify what this means and what is the impact.
There was a problem hiding this comment.
So we would have to do the same for beta (I took this sentence from there).
| @@ -24,6 +24,46 @@ This custom property allows you to identify some components of your | |||
| documentation as beta. Find out more in our [dedicated | |||
| section](/help/specification-support/doc-beta). | |||
|
|
|||
| ## Give precision to the state of your features (`x-state`) | |||
There was a problem hiding this comment.
I think the wording could be more impactful here.
Our users have often referred to this feature as “badges.” Therefore, I’d lean towards something like “Operation Status Badges”, “Endpoint Status Badges", or even "Status Badges". Or maybe something around "tag" ?
It should be something easily searchable using terms like “status” or “badge.”
There was a problem hiding this comment.
I fully agree that it should be mentioned up there!
As of 'tags' or 'badges', you're also right. Badges are tags you can't interact with. So we should harmonize to 'badges' everywhere.
There was a problem hiding this comment.
If you share a link to this example, I may be able to suggest a better screenshot. For instance, I could check if it’s the right dimensions, follows the appropriate template, and perhaps add a highlight to emphasize the badge.
There was a problem hiding this comment.
I sent you the API, if you want a better image 😌
| @@ -24,6 +24,46 @@ This custom property allows you to identify some components of your | |||
| documentation as beta. Find out more in our [dedicated | |||
| section](/help/specification-support/doc-beta). | |||
|
|
|||
| ## Give precision to the state of your features (`x-state`) | |||
|
|
|||
| This custom property can be added inside an operation or a property to identify it with a custom tag. | |||
There was a problem hiding this comment.
I might have added some contextual elements around the feature, such as use cases or examples of how it could be valuable.
There was a problem hiding this comment.
We have the use cases from this week's lead.
For existing clients, it was use to mention the version of the API this element was added in ("Added in 1.2.3"), or to mention a "Technical Preview", so to explain that it's still under heavy development.
Hi!
I pushed a first draft to add the x-state in the documentation.
While writing it, I was wondering if it wouldn't make sense to have a global category (instead of Beta) that talks about the x-state and the x-beta, as the two can be combined.
It's also quite a long content, if we want to show a code example (and I think that's really important)
For now, I added it in the "Speficication extensions" page.