[documentation]: documentation feedback

[nnaydenow]

Enums in JSDoc (component issue) (storybook issue)

Note: API dropdown is not shown for subcomponents (f.e. ui5-option, ui5-table-row, etc.) As for now, do not remove the jsdocs for them.

Properties that are using enum as a type have enum values as a list inside jsdoc comment that describes the property (Avatar's colorScheme property). Storybook provides a way to display the enum values natively and also a select dropdown where you can choose the value that has to be used.

Expected solution:
Remove the enum values from the jsdoc comments

Note - as some enums are missing from the dropdown a central solution is also needed for components that use enums from other packages.

Story names (component issue)

A lot of the components' stories have very long name that wraps and makes the side navigation to look not that good.

Expected solution:
Rename the stories with shorter names

A lot of simple stories (component issue)

A lot of the components' stories illustrate very little features and most of the stories seems to be redudant.

For example:
Switch component has 5 simple stories and every different story illustrates a simple property. These behaviors could be easily achieved by playing with the basic dynamic sample (one of the biggest features of the storybook)

Possible solution:
Group the samples and combine them.

Revise story names (component issue)

Some of the component stories have not descriptive names and a lot of repetition like:

Possible solution:
Revise the name and remove the repetition

Basic stories (component issue)

Most of the components provide a basic story and others not.

Possible solution:
Add basic story for every component.

Component name appears in CamelCase (component issue)

Components names looks bad in CamelCase without spaces.

Possible solution:
Find a way component name to be displayed with spaces: FlexibleColumnLayout => Flexible Column layout

Missing attributes (storybook issue)

In API table only properties appear and respectively attribute is missed (accessibleNameRef f.e.). That should be handled generally.

Logo navlink (storybook issue)

Clicking on the logo should navigation to landing page, but it navigates to https://sap.github.io/ui5-webcomponents/playground/?path=/docs/docs-getting-started-first-steps--docs

API Table wrong tab name (storybook issue) #7436

Some tab names inside API table are visualised wrong by adding Ui5 prefix before the tab name https://sap.github.io/ui5-webcomponents/playground/?path=/docs/main-select--docs

String properties (TBD - as of now - storybook issue)

Some string properties are written inside quotes and if you write value without "" it appears as a wrong value.
https://sap.github.io/ui5-webcomponents/nightly/playground/?path=/story/main-colorpicker--basic - for color property

HTML add-on. (storybook issue)

It doesn't visualize the decorators.
Example here:
https://sap.github.io/ui5-webcomponents/playground/?path=/story/main-dialog--bar-in-dialog
In the separate example the styles are not visible. They should look like this (screenshot from "docs" section):

Components/Samples issue

Styles in api.css file.

This file is created for the old Playground, but is is not deleted yet the styles in it are applied to the new Story book samples.
The best approach is to move the corresponding styles to every Story book sample file. This way they will be visible to the users.

Card with table

1. Open https://sap.github.io/ui5-webcomponents/playground/?path=/docs/main-card--docs#with-table
2. Look the table inside the card

[ivoplashkov]

Hello collegues,

@nnaydenow has provided some well described feedback and issues related to the Storybook, which require your attention.
Could you please check?

Thank you in advance!
Best regards,
Ivaylo

[nnaydenow]

Hi @ivoplashkov,

It's this is cross team issue and it has to be addressed by every team separately since Topic P are responsible only for the story book and their stories.

[LidiyaGeorgieva]

Hello,

I noticed a problem in the HTML add-on. It doesn't visualize the decorators.
Example here:
https://sap.github.io/ui5-webcomponents/playground/?path=/story/main-dialog--bar-in-dialog
In the separate example the styles are not visible. They should look like this (screenshot from "docs" section):

Best Regards,
Lidiya

[LidiyaGeorgieva]

@SAP/ui5-webcomponents-topic-p, @SAP/ui5-webcomponents-topic-rl, @SAP/ui5-webcomponents-topic-b,
please check also if there are styles for your Story book samples in this file: packages/playground/assets/css/api.css.
This file is created for the old Playground, but is is not deleted yet the styles in it are applied to the new Story book samples.
The best approach is to move the corresponding styles to every Story book sample file. This way they will be visible to the users.